Gauge

A React component in Beamline's Charts & data-vis category.

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).
A quota made of parts (usage-meter).
Progress through a task (progress).
A number with its trend (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

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 · Connect your agent