brand-ui — Gauge

import { Gauge } from "@elabs-ai/components-charts";

Install

npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-charts

Skipping the @source line is the most common first failure: Tailwind does not scan node_modules, so every component renders unstyled. The one-time wiring

Prompt for your coding agent

Paste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.

Add the brand-ui Gauge chart (from @elabs-ai/components-charts) to this project.

1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`.
2. Look Gauge up before writing code: `npx -y @elabs-ai/components-cli docs Gauge` prints its real props, variants, what it pairs with and what to avoid.
3. If @elabs-ai/components-charts is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-charts` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-charts`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`.
4. Use it here: [the screen or file, and what it should show]
5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop.
6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.

Use it for

Where does one number stand? One value on a dial.
a single value against a target or threshold bands

Avoid

the trend over time matters more than the instant — use a line chart
A gauge for a value with no meaningful maximum — that is a MetricCard, not a dial.
A gauge per KPI in a grid — a row of dials reads worse than a MetricGrid; use one for the headline only.
Encoding the threshold by colour alone — pair the band with a label or a tick.

Works with

Used inside

Pairs with

MetricGrid

Examples

8 live examples

Default

Notched arc gauge, no milestones — the pre-existing (unaffected) default.

With milestones (F11)

Milestone dots at 25/50/75/100 with a "N ticks to go" caption — lieflat F11. `totalNotches={40}` and `value={32}` reproduce the finding's own example (`32% ⇒ 13 active notches ⇒ 27 remaining` → "27 TICKS TO GO").

Milestones Only

Milestones alone, no caption — the two additive props are independent.

Long Caption

A caption roughly 2x the `WithMilestones` fixture's length (#248). It must wrap inside the donut hole rather than growing across the tick arc.

With Target

A radial tick crossing the notch band at `target` — a quarterly goal.

With Thresholds

Short outer-rim ticks naming bands — colour is not status here, only the accessible text names the band.

Target And Thresholds

Both together — the accessible description composes to "72 of 100, target 80, band Good".

Accessible Name

`accessibleLabel`/`accessibleDescription` (#290) — a named, focusable figure.

API

`Gauge`

Prop	Type	Description
`value`required	`number`	Fill level 0–100
`totalNotches`	`number`	Number of arc notches
`spacing`	`number`	Percentage of the arc reserved for gaps between notches
`notchCornerRadius`	`number`	Corner fillet radius for each notch corner (pixels). 0 = sharp corners; higher values read more rounded; geometry clamps so large values approach a capsule / near-circular silhouette.
`uniformWidth`	`boolean`	`true` = rectangular notches; `false` = tapered toward the center
`startAngle`	`number`
`endAngle`	`number`
`useGradient`	`boolean`
`activeGradient`	`readonly [string, string]`	Override the active-notch gradient with two explicit hex stops to interpolate along the arc. When omitted (the default), notches use the theme chart palette (`--chart-1` → `--chart-5`) — no hardcoded colors.
`inactiveGradient`	`readonly [string, string]`	When `useGradient` is true, inactive notch colors interpolate between these hex stops. Defaults to {@link activeGradient} when omitted.
`centerValue`required	`number`	Value passed to {@link PieCenterShell} / NumberFlow
`defaultLabel`	`string`
`prefix`	`string`
`suffix`	`string`
`formatOptions`	`ChartStatFlowFormat`
`inactiveFill`	`string`	Inactive / track notch fill — CSS color or `url(#patternId)` (define patterns in `children`).
`activeFill`	`string`	Active notch fill — CSS color or `url(#patternId)`. When set, overrides solid / gradient active fills for that layer.
`inactiveFillOpacity`	`number`	SVG `fill-opacity` for inactive / track notches (0–1). Default 1 — the track rung is already tuned lighter than the hairline ink.
`activeFillOpacity`	`number`	SVG `fill-opacity` for active notches (0–1). Default 1.
`children`	`ReactNode`	`PatternLines`, gradients, etc. — rendered inside `<defs>` (same convention as `PieChart` children).
`className`	`string`
`width`	`number`	Explicit pixel size. When omitted, the gauge fills its parent; give the parent a size (e.g. `min-w-[300px]` + aspect box) for responsive layouts.
`height`	`number`
`minWidth`	`number`	Minimum width (px) when using the built-in responsive wrapper. Default 300
`notchLengthPercent`	`number`	Radial depth of notches as a % of the built-in default (outer 42% / inner 28% of `size`). 100 = full length; lower values pull the inner edge toward the outer arc. Clamped 5–100.
`enterTransition`	`Transition`	Framer Motion transition for notch enter animation (opacity / scale).
`enterStaggerScale`	`number`	Scales notch stagger delays relative to default timing (1 = reference).
`milestones`	`number[]`	Milestone values (0–100) marked with a small dot on the dial and a halo-text number just outside the notch band, joined by a short dotted leader — e.g. `[25, 50, 75, 100]` (lieflat F11). Setting `milestones` reserves a small radial margin so the leader + label never clip the gauge's own box; a `Gauge` with `milestones` unset renders its pre-existing, unaffected geometry. #248.
`remainingLabel`	`(remaining: number) => string`	Caption rendered under the center value/label. Receives the number of notches remaining (`totalNotches - activeNotches`) and returns the caption text — e.g. `(remaining) => \`${remaining} ticks to go\`` renders as "27 TICKS TO GO" (lieflat F11; the caption is rendered upper-cased via CSS, so pass ordinary sentence case). Unset (default) renders no caption.
`target`	`number`	A radial tick crossing the notch band at this value (0–100) — e.g. a quarterly target. Reuses the same value→angle mapping as notches/ milestones. Unset (default) renders no tick and the dial's geometry is unaffected.
`thresholds`	`GaugeThreshold[]`	Short outer-rim ticks (furniture — `--chart-grid`, `CHART_HAIRLINE_WIDTH`) marking named bands (e.g. `{ value: 75, label: "Good" }`). No colour zones — colour is not status here, only the accessible text names the band a value falls in. Unset (default) renders no ticks.
`messages`	`Partial<GaugeLabels> & ChartMessages`	This gauge's own words (the `messages` group, RM-191): the word the composed accessible text uses for the target (`target`), and overrides of the catalogue's `charts.*` keys it prints (`charts.gauge.defaultLabel`), for this gauge only. The two key sets never collide: a catalogue key always starts with `charts.`.
`labels`	`Partial<GaugeLabels>`	@deprecated Use `messages` — the same object, the same keys (RM-191, ADR 0042 A.1). Still read until 7.0.0, with one development warning; when both are set, `messages` wins.
`accessibleLabel`	`string`	Accessible name for the chart region. AT announces this when the container receives focus or is read in flow. Example: "Monthly revenue bar chart"
`accessibleDescription`	`string`	Supplemental description (series names, value ranges, last values, etc.). Rendered as a visually-hidden `<span>` associated via `aria-describedby`. Example: "Series: Revenue, Expenses. Range: 0–25,000."

Also accepts: ChartA11yProps