Dynamic Range Gauge

Dynamic Range Gauge

A radial gauge for a single telemetry or attribute value, with color-coded ranges drawn directly on the arc — so it’s immediately clear whether a reading is normal, warning, or critical, instead of reading a bare number and mentally checking it against a threshold.

Features

• Color-coded range bands on the gauge arc, each range split at the current value — the reached portion renders at full color, the remaining portion fades to a configurable opacity, giving a “how far into this zone” cue per band
• Ranges can be defined statically in widget settings, or driven dynamically from an entity attribute or timeseries key containing JSON — so the same dashboard/widget can show different thresholds per entity without manual reconfiguration
• Min and max value can each be fixed, or sourced from an entity attribute/timeseries key, so the scale itself can vary per entity
• Value text and/or pointer color can automatically match whichever range the current value falls in
• Smoothly animated value transitions — pointer, value text, and range split all animate together in lockstep
• Customizable title and value typography (color, font, weight, style)
• Built on ECharts

Data keys

This widget reads up to four data keys from the same data source, each serving a different purpose. Which key does what is controlled by name matching in settings — a key’s name or label must match what’s typed into the corresponding setting field.

Purpose	Setting	Default key name
Main value	Main value datasource key name	(auto-detected)
Min value	Min value datasource key name	minValue
Max value	Max value datasource key name	maxValue
Ranges (JSON)	Ranges datasource key name	colorZones

If Main value datasource key name is left blank, the widget uses the first data key that isn’t already reserved for min/max/ranges — for a single-value gauge, this setting can usually be left untouched.

Configuration

General

• Main value datasource key name — which data key drives the gauge value and pointer position. Leave blank to auto-select the first key not reserved for min/max/ranges.
• Enable animation — when on, the pointer, value text, and range split all glide smoothly to the new value on every update. When off, the gauge jumps instantly to each new reading.
• Animation duration (ms) — how long that glide takes. Higher values look smoother but feel laggier on fast-changing telemetry; lower values feel snappier but can look jumpy. Only visible/relevant while animation is enabled.
• Show title — shows or hides the label above the gauge (taken from the main value key’s label/name).
• Title style (color, font) — controls the title text’s color, size, family, weight, and style. Only relevant while the title is shown.

Min/Max value

These two settings groups control the numeric span the gauge arc represents — i.e., what “empty” and “full” mean.

• Min/Max value source — Fixed value uses a single number you type in, the same for every entity. Entity attribute / Entity timeseries instead reads the bound from a data key on the entity, so different entities can have different scales (e.g. one machine’s normal range is 0–100, another’s is 0–5000) without editing the widget per entity.
• Min/Max value (fixed) — the literal number used as the bound, when source is Fixed value.
• Min/Max value datasource key name — which data key supplies the bound, when source is Entity attribute or Entity timeseries.

Changing min/max reshapes the entire gauge: axis tick labels, the position of the pointer for a given value, and — critically — where each range band lands, since range boundaries are absolute values interpreted against this same min/max span.

Gauge ranges

Controls the color bands drawn on the arc. This is what turns a plain gauge into a “traffic light” style indicator.

• Default color — the single flat color used for the whole arc when ranges are switched off, and also the fallback color if the ranges source returns nothing usable (e.g. a missing or malformed attribute). Always visible regardless of the toggle below, since it’s always the fallback.
• Use gauge ranges — master on/off switch. Off: the gauge behaves like a plain single-color gauge, filling solidly from min up to the current value in Default color. On: the arc instead shows the configured range bands end-to-end, and the fill behavior changes to the split/fade effect described below.
• Gauge ranges source — Static reads the ranges list you define directly below in settings, fixed for every entity showing this widget. Entity attribute/timeseries (JSON) instead reads the ranges from a data key whose value is a JSON array — so different entities (or device types) can show different thresholds using the exact same dashboard/widget instance.
• Ranges datasource key name — which data key holds that JSON array, when source is set to the JSON option. The value must look like [{"to":40,"color":"#7cb342"}, ...].
• Value text color follows active range — when on, the numeric value display recolors to match whichever range the current reading currently falls into (e.g. text turns red once the value enters the red band). When off, the value text keeps its own configured color regardless of range.
• Ranges (static list) — the actual band definitions, each with an Up to (upper bound, absolute — same scale as min/max) and a Color. Bands are implicitly contiguous: the first band starts at min, each subsequent band starts where the previous one ended, and the last band should reach max. Only shown/used when the source is Static.

Visual effect of ranges being active: the arc is always fully covered by band colors end-to-end (not just up to the current value). The portion of each band before the current value renders at full color (“reached”); the portion after renders faded, using Track opacity from the appearance section below. This means you can see both which zone the value is currently in, and how much of that zone (and the ones before it) has been covered — similar to a fuel gauge, but color-coded by zone instead of a single fill color.

Gauge appearance

• Show axis ticks — shows or hides the small tick marks around the arc.
• Show axis labels — shows or hides the numeric labels next to those ticks (every other tick is labeled to avoid crowding). Only relevant while ticks are shown.
• Axis ticks/labels color — the color used for both the tick marks and their labels.
• Show value text — shows or hides the large numeric readout in the center of the gauge.
• Value text style (color, font) — the readout’s color, size, family, weight, and style. The color here is overridden automatically if Value text color follows active range is on and ranges are active.
• Track opacity — how faded the not-yet-reached portion of the arc appears. With ranges off, this fades the single background track behind the solid progress fill (e.g. 0.12 gives a soft, mostly-transparent backdrop). With ranges on, this same opacity is applied to the unreached portion of each band, as described above. Lower values (closer to 0) make the unreached portion nearly invisible; higher values (closer to 1) make it nearly as bold as the reached portion, reducing the visual contrast between “covered” and “remaining.”
• Show pointer / needle — shows or hides the radial needle indicating the exact current value.
• Pointer / needle color — the needle and its center anchor dot’s color, used when Needle color follows active range is off (or ranges are inactive).
• Needle color follows active range — when on and ranges are active, the needle and anchor dot recolor to match the current range, the same way the value text can. Only shown while the pointer is visible.

Requirements

Requires the ECharts library, referenced on the widget’s Resources tab (bundled from cdnjs.cloudflare.com, e.g. https://cdnjs.cloudflare.com/ajax/libs/echarts/6.1.0/echarts.min.js). If your ThingsBoard instance blocks external CDN resources, host the same version locally and update the Resources tab entry.

Tips

• If the gauge shows a single flat color instead of bands, check that Use gauge ranges is on, and that either the static Ranges array has entries or the configured ranges key resolves to valid JSON — a parse failure is logged as a console warning and falls back to the default color silently.
• Range to values 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 attribute as well, so each entity’s bands stay proportionate to its own scale.
• For fleets of similar devices with different normal operating ranges, push a colorZones shared attribute per device (or device profile) via a rule chain, then point every dashboard instance of this widget at that same attribute key — thresholds stay correct per device without touching the dashboard.__