Threshold bar

Threshold bar

Shows the latest value of one key on a horizontal bar split into color zones, so a number is read together with the range it falls into. The zone edges, the range and the target can be fixed numbers or keys the device reports, which lets every device carry its own limits without editing the dashboard.

Features

• Color zones with labels; the label of the current zone is shown next to the value
• Fill mode (the bar fills to the value) or band mode (the bar shows all zones, the value becomes a marker)
• Optional target marker for a setpoint
• Zone edges, range and target accept ${key} and follow that key live
• Off-scale values are pinned to the end of the bar and flagged with chevrons
• Layout scales with the card, or from one font size you set
• No external libraries

Data keys

• any numeric key (timeseries or attribute) — the value shown on the bar. One entity and one key are used; the label, units and decimals of the bar come from the data key configuration.

Keys referenced as ${key} in the settings are read by the widget itself and must not be added to the datasource. For each name the widget looks for both an attribute and a timeseries key of the same entity, in any attribute scope, and prefers the attribute when both exist. It follows them live, so raising a limit on the device redraws the bar without touching the dashboard.

How the zones work

A zone is defined by one number: where it starts. It runs up to the start of the next zone, and the last zone runs to the end of the range. Three zones starting at 0, 5 and 20 on a 0–100 range therefore cover 0–5, 5–20 and 20–100. Because a zone has a start and no end, zones can neither overlap nor leave a gap.

• The order of the rows does not matter — zones are sorted by their start value, and if two share a start, the lower row wins.
• A zone starting at or below the start of the range colors the left end of the bar rather than adding a zone of its own.
• A zone starting beyond the end of the range is not drawn, but a value that reaches it still picks up its color.
• Anything below the lowest zone takes Color below the first zone, so a range that begins before the first zone is still colored.
• The zone the value falls into sets the color of the fill in fill mode, and the color of the label next to the value in both modes. That label is the zone’s own Label, or its bounds when the label is empty — so the current zone is always readable.

Values

• A value above the end of the range is drawn at the right end of the bar with ››; a value below the start is drawn at the left end with ‹‹. The range is never stretched to fit an outlier, so bars stay comparable between cards.
• A value that is missing, empty, boolean or not a number is treated as no value: the bar is empty and the reading shows --.
• If a ${key} cannot be read, that zone simply does not exist. An unreadable range falls back to 0 and to the last zone plus 20%.
• The value, the ticks and the zone bounds all use the units and decimals of the data key.
• The bar shows the latest reported value and does not aggregate over the dashboard time window, so a device that stops reporting keeps showing its last value.

Configuration

Setting	What it does
Show the zones as a colored band	Off: the bar fills to the value in the color of its zone. On: the bar shows every zone and the value becomes a marker
Range starts at / Range ends at	A number, or ${key}
Target	Optional. A number, or ${key} to follow a setpoint reported by the device
Zones	Each row is a zone: where it starts, its color, its label
Color below the first zone	Used only when the lowest zone starts above the start of the range
Show the name of the data key / the value / the range and zone edges	Hide the parts the dashboard already says elsewhere
Colors	Bar, empty part of the bar, zone edge lines, value marker, target marker, key name and units, value, ticks
Scale everything to the size of the card	On: fonts and the bar follow the card. Off: one value font size drives all of them