AQI Gauge

Who it’s for

Dashboard authors putting air quality on a wall display or a shared floor-plan, where the question is “is the air in this room fine right now?” and nobody is going to hover over a chart to find out. The number alone does not answer it — 2.7 and 178 mean nothing without knowing which band they fall in — so the reading is shown on a dial that names the band it landed in.

What it does

A sensor reporting 2.7 puts the pointer in the yellow segment and reads Moderate in the middle of the dial; the other bands stay muted, so the state is legible from across a room before the number is.

• A traditional 240° dial with coloured bands, band titles around the outside, a pointer, and the reading with its band name in the middle
• Accepts a numeric level (0–5), a measured scale with real breakpoints (0–500 AQI), or plain text the device sends (ok, not ok, super) — the scale type is detected from the band configuration, there is no mode to pick
• Text readings are matched case-insensitively against the band value, and against the band title as a fallback
• Band titles sit outside the dial and the radius adapts to the longest one, so nothing is clipped in a narrow widget
• Optional pointer, reading, band name and hover tooltip; hiding the pointer moves the reading into the middle of the dial
• Everything scales with the widget — fonts, ring thickness, pointer and titles are derived from the card size
• A key that stops reporting fades the dial instead of resting on the first band
• Shows one reading at a time: it does not chart history, compare rooms, or aggregate several sensors

How to set up

Add the widget, point it at one entity, and give it one key. Everything else has a working default — a 0–5 air quality level with six named bands.

Data keys

Key	Role	Type	Description
Any key name (user-configured)	The reading on the dial	Timeseries or Attribute	The current air quality reading. Numbers (2, 2.7, 178) are matched against the numeric bands and the pointer points at the exact value. Strings (ok, Moderate) are matched against the band values, then titles, and the pointer points at the middle of the matching band.

The widget uses exactly one key. Units and Decimals come from the data key itself — the widget-level copies of those fields are hidden.

Empty values, null and non-numeric readings on a numeric scale are treated as no data: the dial fades, the pointer is hidden, and the middle shows the No data display message from the widget’s appearance settings, or -- when that is empty. A string that matches no band is shown as it arrived, with the pointer hidden. Readings below the first band or above the last are clamped to the ends of the dial, but the reading itself is still displayed unchanged.

Default bands

Range	Title	Colour
0–1	Very Good	Green #5CC8A0
1–2	Good	Light green #9BD173
2–3	Moderate	Yellow #F5CE5E
3–4	Sufficient	Orange #F49E5C
4–5	Poor	Red #E56E64
5–6	Very Poor	Purple #A85585

Offline instances

The dial is drawn with Apache ECharts, declared as a widget resource and loaded from cdn.jsdelivr.net. On an instance with no outbound internet access, upload echarts.min.js under the widget’s Resources tab and point the resource at the local copy — until then the widget still shows the reading and the band name as text.

How to customize

• To describe your own air quality levels — edit the Bands list. Each row’s Value is the reading that band starts at, Title is what appears around the dial and in the middle, and Colour is the segment colour, with the title drawn in a darker shade of it. Add or remove rows freely; the dial, the titles and the tooltip follow. Numeric bands are sorted automatically, so the order in the form does not matter.
• To use official AQI breakpoints instead of a 0–5 level — replace the band values with the breakpoints and set the scale to 0–500. See the table below.
• To show text states the device sends — put the exact strings (ok, not ok, super) in the band values. If any value is not a number the whole scale is treated as text: bands become equal segments in the order given, Scale starts at and Scale ends at are ignored, and the middle of the dial shows the band title instead of a number.
• To change where the dial starts and ends — set Scale starts at (0) and Scale ends at (6). Numeric scales only. Both are widened automatically rather than cutting a band off: the start drops if the first band begins below it, the end rises if it would fall inside the last band.
• To get a bigger dial in a narrow widget — turn off Show band titles outside the dial.
• To hide the pointer — turn off Show the pointer; the reading moves into the middle of the dial. Pointer colour (#37474F) sets the pointer and the hub outline.
• To show only the number, or only the state — turn off Show the band name or Show the reading. The band name hides itself automatically when it would just repeat the reading.
• To turn off the tooltip — turn off Show details on hover. It otherwise reports the reading, the band title and the band range.
• To change what a silent sensor shows — set No data display message in the widget’s appearance settings.
• To fix the number of decimals or add a unit — set them on the data key, not on the widget.

US AQI breakpoints

Range	Title	Colour
0–51	Good	Green #5CC8A0
51–101	Moderate	Yellow #F5CE5E
101–151	Unhealthy for sensitive groups	Orange #F49E5C
151–201	Unhealthy	Red #E56E64
201–301	Very unhealthy	Purple #A85585
301–500	Hazardous	Maroon #8E3B5B

Tips

• A band’s Value is where it starts, not where it ends. Published AQI tables are written as 0–50, 51–100, 101–150; entered here those are 0, 51, 101. Copying the upper bound into the field is the one mistake that silently shifts every band by one.
• On a text scale the segments are equal and follow the order you typed them, so the pointer’s position carries no magnitude — order the bands deliberately, best to worst or worst to best, and let the colours do the rest.