Gauge Meter
Needle gauge: a spring-swinging needle, banded color arcs, and a rolling value.
An SVG semicircular gauge whose needle swings to the target value on a low-damping spring, overshooting and settling back. Banded color arcs (green/amber/red, with customizable stops) sit alongside tick marks, the central value shares the same spring as the needle so the two roll in sync, and the color bands the needle has not yet reached are dimmed.
npx shadcn@latest add https://webberui.com/r/gauge-meter.jsonPlayground
Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.
<GaugeMeter />
Installation
npx shadcn@latest add https://webberui.com/r/gauge-meter.jsonOr, once registries are configured in components.json, install it as @webberui/gauge-meter.
Usage
import { GaugeMeter } from "@/components/ui/gauge-meter";
<GaugeMeter
value={72}
unit="%"
label="CPU usage"
stops={[
{ to: 60, color: "#10b981", label: "Smooth" },
{ to: 85, color: "#f59e0b", label: "Elevated" },
{ to: 100, color: "#ef4444", label: "Overloaded" },
]}
/>Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | The target value; when it changes, the needle swings there on a spring (overshooting and settling back) |
min | number | 0 | Minimum of the gauge |
max | number | 100 | Maximum of the gauge |
stops | GaugeStop[] | green/amber/red default | Banded color arc configuration, each band { to, color, label? }; when omitted, green/amber/red at 60% / 85% / 100% is used |
unit | string | — | Unit text after the value, such as "%" or "km/h" |
label | string | — | Gauge title, shown below the gauge |
size | number | 240 | Gauge width (px); the height scales automatically at a 200:148 ratio |
decimals | number | 0 | Decimal places shown for the central value |
className | string | — | Forwarded to the outer container |
GaugeStop: to is the end value of that color band (the bands must increase, and the last one should ideally equal max), color is any valid CSS color, and label is the status text shown when the current value falls inside that band.
Accessibility
- The container uses
role="meter"together witharia-valuemin/aria-valuemax/aria-valuenowandaria-valuetext, so assistive technology announces the target value rather than an intermediate animation value - The SVG itself is marked
aria-hiddento avoid announcing the same thing twice alongside the meter semantics - When the user has "reduce motion" enabled at the system level, the needle and the number jump straight to the target value with no spring swing played
- The value uses
tabular-numsmonospaced figures, so the layout does not judder while it rolls