Gauge

A 270-degree ring that shows one value against a known range, with optional labelled thresholds that set its tone and state.

When to use

• A single reading against fixed bounds: storage, a quota, a seat count, a health score.
• When the state matters as much as the number; add thresholds so the band label (Healthy, Filling up, Critical) is spelled out, not left to colour.
• Not for task progress; use Progress or ProgressRing. For plan limits, use UsageMeter. Not for a trend over time; use Sparkline or LineChart.

Usage

import { Gauge } from "@/components/iris/gauge/gauge";

h(Gauge, {
  label: "Monthly pageviews",
  value: 71,
  detail: "17,750 of 25,000",
  thresholds: [
    { from: 0, tone: "success", label: "Healthy" },
    { from: 70, tone: "warning", label: "Filling up" },
    { from: 90, tone: "danger", label: "Critical" },
  ],
});

Props

Prop	Type	Default	Description
value	number	required	Current value between min and max. The readout shows it as a percentage of the range.
min	number	0	Lower bound.
max	number	100	Upper bound.
label	string	required	What is measured; shown under the ring.
detail	string	—	Secondary caption, such as 2.6 of 10 GiB.
tone	"accent" | "success" | "warning" | "danger"	"accent"	Ring colour when no threshold applies.
thresholds	{ from: number; tone; label: string }[]	—	Bands by starting value, in the same units as value. The highest band reached sets the tone and shows its label inside the ring.

Notes

• Accessibility: the ring is a role="meter" with min, max, current value and aria-valuetext including the band label. The SVG and the animated digits are hidden from assistive technology.
• Motion: the ring fills once when half in view, then springs to new values; the band label changes exactly as the count crosses a threshold. With reduced motion it jumps straight to the value.
• Size: up to 176px wide and scales down in narrower columns. Centre it in its container.
• Reads --accent, --accent-ink, --green, --orange, --red and --ink-3.