# Gauge

A React component in [Beamline](https://beamline.io/)'s [Charts & data-vis](https://beamline.io/components/charts) category. Live demo: https://beamline.io/components/gauge

One value against a known range: a semicircle, a 270° dial or a full ring, filled or with a needle, coloured bands with their names (healthy, busy, saturated), an optional target tick, the value large in the middle, and a meter that assistive technology reads.

## Use it for

- A single reading against a known range with thresholds: CPU, error budget left, health score, NPS.

## Not for

- Several values side by side ([bar-list](https://beamline.io/components/bar-list)).
- A quota made of parts ([usage-meter](https://beamline.io/components/usage-meter)).
- Progress through a task ([progress](https://beamline.io/components/progress)).
- A number with its trend ([metric-card](https://beamline.io/components/metric-card)).

## Anatomy

- figure
- track (bands drawn along it when given)
- value arc (fill) or needle with hub
- target tick and its label
- min and max labels
- value (rolling digits)
- band name (badge with glyph)
- title and description (caption)

## Variants

- **0**: shape: semi (180°) · dial (270°) · ring (360°)
- **1**: indicator: fill · needle
- **2**: size: sm · md · lg
- **3**: bands (tone + label per threshold)
- **4**: target

## States

- loading (ring skeleton)
- unmeasured (value null: hatched track, “Not measured”, no needle)
- within each band (the band's tone and name)
- out of range (clamped to the ends; the text keeps the real value)
- right-to-left: the arc still runs from min on the left (a scale, not reading order)

## Keyboard

- Not focusable: a meter is read, not operated. role="meter" with aria-valuenow/min/max and aria-valuetext including the band name

## Motion

Sweeps from the minimum once on first draw; later values glide to the new angle and the digits roll; all instant under reduced motion.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number \| null` | — | The reading; null renders unmeasured. |
| `min / max` | `number` | — | The range. Default 0–100. |
| `bands` | `GaugeBand[]` | — | { from, label, tone } in ascending order; each runs to the next one's from (the last to max). |
| `target` | `{ value: number; label: string }` | — | A tick on the track: a goal or a limit. |
| `shape` | `"semi" \| "dial" \| "ring"` | — | Default semi. |
| `indicator` | `"fill" \| "needle"` | — | Default fill. |
| `size` | `"sm" \| "md" \| "lg"` | — | Default md. |
| `format` | `(value: number) => string` | — | How the value and range read: "72%". |
| `title / hideTitle / description` | `string / boolean / ReactNode` | — | The meter's name and its caption. |
| `loading` | `boolean` | — |  |
| `className` | `string` | — |  |
| `classNames` | `GaugeClassNames` | — |  |
| `style / ref` | `CSSProperties / Ref<HTMLElement>` | — | Visual root styles and native root ref. |

## Dependencies

`motion`

## Import

```tsx
import { Gauge } from "@/components/gauge/gauge";
```

## Get it

Gauge is part of Beamline: 190 React components and screens your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 one payment (regular $200), no subscription, a year of updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Charts & data-vis

- [Activity heatmap](https://beamline.io/components/activity-heatmap): A calendar of daily counts, one cell per day on a sequential ramp: weeks across, weekdays down, month and weekday labels, a legend scale, hatched days…
- [Area chart](https://beamline.io/components/area-chart): Amounts over time as filled areas: overlapping, stacked or as shares of 100%, five fills, two strokes, five curves, a range handle; gaps for missing…
- [Bar chart](https://beamline.io/components/bar-chart): Amounts by category as bars: columns or rows, grouped, stacked or as shares, reference lines, five looks (rounded, cells, trace, isometric, monospace), a…
- [Composed chart](https://beamline.io/components/composed-chart): Different measures on one time axis: bars, lines and areas per series, a left and a right value axis with their own formats, and reference lines.
- [Line chart](https://beamline.io/components/line-chart): Values over time as lines: curves, point markers, dashed series for forecasts, reference lines for limits and targets, an optional zero baseline and a…
- [Pie chart](https://beamline.io/components/pie-chart): A few shares of a whole as a pie or donut, with spaced slices, percent labels, a centre readout and a list of every slice with value and share; hovering…
- [Radar chart](https://beamline.io/components/radar-chart): A few series compared across the same five to eight dimensions as polygons on a polygon or circle grid; hover or arrow keys pick a dimension and read…
- [Radial chart](https://beamline.io/components/radial-chart): Progress of a few measures toward their targets as concentric rings, full or half circle, with a centre readout and a list of each ring's value, target…
- [Ridgeline](https://beamline.io/components/ridgeline): Distributions per group as overlapping density ridges (response time by region, order size by plan): an overlap control, median and p95 readouts per row…
- [Sankey chart](https://beamline.io/components/sankey-chart): Flows between stages as bands whose width is the amount: sources to pages to outcomes, budgets to teams; hovering or focusing a node lights its flows and…
- [Slope chart](https://beamline.io/components/slope-chart): Change between two points in time per item, by value or by rank: labels on both sides that never collide, rising and falling told by the end marker (▲ ▼)…
- [Sparkline](https://beamline.io/components/sparkline): A compact trend beside its value: point along it or focus it and use ← → to read each point; nulls are gaps. TrendLine is the bare line.
- [Streamgraph](https://beamline.io/components/streamgraph): Stacked flows over time around a centre baseline, with silhouette, wiggle, expand (shares) and zero offsets: a legend that turns layers on and off, a…
- [Treemap](https://beamline.io/components/treemap): Nested rectangles sized by value (spend by team, then service), squarified so tiles stay close to square: labels that fit or hide, hover and focus…
- [Waffle chart](https://beamline.io/components/waffle-chart): Units of a whole as a grid of cells by category (seats used of a plan, tickets by channel): a 10×10 grid by default, hatched cells for units whose…