Gauge
A radial dial for a single value — with threshold zones, an optional needle, ticks, and a target.
@garn/ui/gaugeDefault
A full-ring dial with a centre readout.
Thresholds
Threshold zones auto-colour the arc + reading; a target tick.
Needle
A half-circle speedometer with ticks + scale.
Sizes
sm / md / lg, with a delta.
Installation
garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.
npx garn-ui add gauge- Registry
gauge- Source
- gauge.tsx
- Deps
d3-shaped3-scale- Registry deps
utils
Import
import { Gauge } from "@garn/ui/gauge";Props
Generated from the component's TypeScript types.
color- Description
- Single-tone fallback when there are no `thresholds`. Token reference.
- Type
string
delta- Description
- Optional trend readout under the value (e.g. a delta).
- Type
React.ReactNode
endAngle- Description
- No description.
- Type
number
label- Description
- No description.
- Type
React.ReactNode
max- Description
- No description.
- Type
number
min- Description
- No description.
- Type
number
numberFormat- Description
- No description.
- Type
Intl.NumberFormatOptions
showScale- Description
- Min / max end labels on the scale.
- Type
boolean
showValue- Description
- No description.
- Type
boolean
size- Description
- No description.
- Type
"lg" | "md" | "sm"
startAngle- Description
- Sweep in degrees, clockwise from 12 o'clock. Default a 270° dial.
- Type
number
target- Description
- A reference marker on the arc; folded into the accessible reading.
- Type
number | { value: number; label?: string; }
thresholds- Description
- Colour zones — auto-colour the arc + reading, and draw the track bands.
- Type
GaugeThreshold[]
ticks- Description
- Number of tick intervals around the arc (0 = none).
- Type
number
valueRequired- Description
- No description.
- Type
number
valueLabel- Description
- No description.
- Type
React.ReactNode
variant- Description
- Filled progress arc (default) or a speedometer needle over the zones.
- Type
"arc" | "needle"
Plus 279 inherited native <div> attributes.
Styling
Target these data-slots and remap these tokens to restyle without forking the component.
[data-slot="gauge"]Overview
Gauge is the KPI dial: a single value on a radial scale, read against optional threshold zones (calm → warning → critical) that colour the arc and the accessible reading. It shows as a filled arc or a speedometer needle, with optional ticks, a scale, and a target marker. It's pure d3-shape SVG — no charting engine — and a meter for assistive tech, so the value is announced.
Guidelines
Use it for one prominent value. A gauge earns its space as a single, glanceable dial; to compare many KPIs or fit a table, a Bullet is denser. For simple linear progress, Progress is lighter.
Let zones do the colouring. Pass thresholds and the arc auto-colours by the active zone and folds the zone label into the reading — don't hand-set color per value. Zones double-encode as bands so the state reads without relying on hue.
Announce the value. It's a meter: give it an aria-label; the value, active zone, and target are folded into aria-valuetext.
Best practices
- Pass
thresholdsfor auto-zone colouring; give it anaria-label. - Use
variant="needle"for a speedometer; settargetfor a reference.
- Don't hand-colour per value when zones express the meaning.
- Don't line up many gauges where bullets would compare better.
Accessibility
- Role
meter
- • role=meter with aria-valuenow (clamped into [min,max]) / aria-valuemin / aria-valuemax; pass an `aria-label`.
- • aria-valuetext folds in the value, the active zone label, and the target (e.g. "94%, Critical, target 80").
- • The centre readout + SVG are decorative; zone colour is paired with the zone label so meaning isn't colour-only.
- Status
- Stable
- Version
v0.3.0- Introduced
v0.2.0
garn doesn't yet record a per-release version history. This reflects the component's current lifecycle state; full changelog entries will appear once the metadata pipeline emits a lifecycle.history field.