Dynamic Range Gauge

Who it’s for

Anyone building one dashboard template for many different kinds of equipment asks “does this reading look normal for this specific machine, not just against a generic threshold?” A fixed gauge answers that only if someone reconfigures it by hand for each one. A solutions provider reusing the same dashboard across customers wants pump A’s normal range to read 0-3000 RPM while pump B’s reads 0-800, from the exact same widget instance. A facility manager scanning a floor of mixed equipment wants every gauge to look “in the green” the same way, even though the underlying numbers mean something different machine to machine.

What it does

A tank-level gauge with a 0-100 scale, a green band up to 40, and a red band above 75 reads a live value of 62: the yellow-to-62 portion of its band fills in full color, the rest of that band and the red band beyond it stay faded — so you see both which zone the tank is in and how close it is to the next one.

• Color-coded range bands are drawn directly on the arc, split at the current value — the reached portion renders at full color, the rest fades, giving a “how far into this zone” cue per band
• Both the range bands and the min/max scale can each come from a fixed setting or a live entity attribute or timeseries key, so the same widget instance can show a different scale and different thresholds per entity
• Value text and pointer color can automatically match whichever range the current value falls in
• The pointer, the value text, and the range split all animate together on every update
• Draws one gauge from one main value key; it does not compare several entities on the same arc or chart the value’s history

Requirements

This widget loads its chart library, ECharts 5.5.0, from a resource it already carries on its own Resources tab (https://cdn.jsdelivr.net/npm/echarts@5.5.0/dist/echarts.min.js), so there is nothing to add for a normal install. If your ThingsBoard instance blocks external CDN resources, host that same file yourself and replace the URL in the widget’s Resources tab — without it, the gauge does not render, and the browser console logs “ECharts library not found.”

How to set up

Data keys

Key	Role	Type	Description
Main value key (setting: Main value datasource key name)	Main value	Timeseries or Attribute	Optional — leave blank to auto-select the first bound key not already claimed by the keys below
Min value key (setting: Min value datasource key name, default minValue)	Scale minimum	Timeseries or Attribute	Only read when Min value source is Entity attribute or Entity timeseries
Max value key (setting: Max value datasource key name, default maxValue)	Scale maximum	Timeseries or Attribute	Only read when Max value source is Entity attribute or Entity timeseries
Ranges key (setting: Ranges datasource key name, default colorZones)	Range bands (JSON)	Timeseries or Attribute	Only read when Gauge ranges source is set to the JSON option; expects an array like [{"to":40,"color":"#7cb342"}, ...]

Keys are matched by name or label against the setting fields above, not a per-key Role. With Main value left blank, the gauge auto-selects the first bound key that Min/Max/Ranges haven’t already claimed — for a single-value gauge, this usually needs no changes. The Min, Max, and Ranges keys are read only when their own source setting is pointed at a key instead of a fixed value or a static list (see the two groups below); leave those on their defaults and none of the three extra keys are needed at all.

Min/Max value

Setting	Default	Effect
Min value source	Fixed value	Fixed value types one number, the same for every entity. Entity attribute or Entity timeseries reads the bound from the Min value key instead, so different entities can have different scales
Min value	0	Used when Min value source is Fixed value
Min value datasource key name	minValue	Used when Min value source is Entity attribute or Entity timeseries
Max value source	Fixed value	Same choice as Min value source, for the top of the scale
Max value	100	Used when Max value source is Fixed value
Max value datasource key name	maxValue	Used when Max value source is Entity attribute or Entity timeseries

Changing min/max reshapes the whole gauge: the axis tick labels, where the pointer sits for a given value, and where each range band lands, since range boundaries are absolute values read against this same min/max span.

Gauge ranges

Setting	Default	Effect
Use gauge ranges	On	Off: the arc fills solidly in Default color from min up to the current value, like a plain gauge. On: the arc shows the configured bands end-to-end with the split/fade fill described in What it does
Gauge ranges source	Static	Static reads the Ranges list defined under How to customize, the same for every entity. Entity attribute/timeseries (JSON) reads the bands from the Ranges key instead, so different entities or device types can show different thresholds from the same widget instance
Ranges datasource key name	colorZones	Used when Gauge ranges source is the JSON option

How to customize

Animation and title

• To turn off the smooth transition — turn off Enable animation; the gauge jumps instantly to each new reading instead of gliding.
• To change how long the glide takes — adjust Animation duration (ms); higher looks smoother but feels laggier on fast-changing telemetry, lower feels snappier but can look jumpy. Only shown while animation is on.
• To hide the label above the gauge — turn off Show title (the label is taken from the main value key’s own label or name).
• To restyle the title — adjust Title style’s color and font. Only relevant while the title is shown.

Range colors and fallback

• To set your own bands — edit the Ranges list; each entry has an Up to boundary and a Color. Bands are implicitly contiguous — the first starts at min, and each next one starts where the previous ended. Only used when Gauge ranges source is Static.
• To change the flat fallback color — adjust Default color; it is used for the whole arc when Use gauge ranges is off, and as the fallback whenever the ranges source returns nothing usable.
• To stop the value text from recoloring by zone — turn off Value text color follows active range; the value keeps its own configured color instead.

Gauge appearance

• To hide the tick marks or their labels — turn off Show axis ticks or Show axis labels (labels need ticks on; only every other tick is labeled to avoid crowding).
• To change tick and label color — adjust Axis ticks/labels color.
• To hide the numeric readout — turn off Show value text.
• To restyle the readout — adjust Value text style’s color and font; this is overridden automatically when Value text color follows active range is on and ranges are active.
• To fade the unreached part of the arc more or less — adjust Track opacity; lower values make it nearly invisible, higher values make it nearly as bold as the reached portion.
• To hide the needle — turn off Show pointer / needle.
• To change the needle’s color — adjust Pointer / needle color; used unless Needle color follows active range is on and ranges are active.
• To make the needle recolor by zone — turn on Needle color follows active range (only shown while the pointer is visible).

Tips

• If the gauge shows one flat color instead of bands, check that Use gauge ranges is on, and that either the static Ranges list has entries or the configured Ranges key resolves to valid JSON — a parse failure is logged to the browser console and falls back to Default color silently.
• Up to values in Ranges are absolute, on the same scale as the gauge’s own min/max, not percentages. If min/max varies per entity, drive Ranges from a per-entity key too, so each entity’s bands stay proportionate to its own scale.
• For a fleet of similar devices with different normal ranges, push a colorZones-shaped attribute per device or device profile from a rule chain, then point every dashboard instance of this widget at that same key — thresholds stay correct per device without touching the dashboard.