Gauge
A speedometer gauge — a value arc over a min–max sweep with threshold zones, ticks, and a needle.
Category: chart · WCAG 2.1-AA · chart, gauge, speedometer, kpi, data-viz
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | — | The value the needle points to. |
min | number | 0 | Minimum allowed value. |
max | number | 100 | Maximum allowed value. |
thresholds | { upTo: number; color: string }[] | — | Coloured zones from min upward; the last should reach max. |
unit | string | — | Suffix after the centre value. |
sweep | number | 270 | Total sweep angle in degrees (270 = a speedometer arc). |
ticks | number | 5 | Major tick count. |
title | string | — | Chart title (also aria-label). |
description | string | — | Supporting description text. |
width | number | — | Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks its container via a ResizeObserver; there is no correct pixel number in a responsive grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for this — charts call it internally. |
height | number | 240 | SVG height in px. Unlike `width`, height does NOT track the container — this is the knob you set to change the chart's aspect. |
className | string | — | Additional CSS class names merged onto the root element. |
plain | boolean | false | Marks only — no ticks/labels. For micro/inline charts. |
Design tokens
--cascivo-color-accent--cascivo-color-foreground--cascivo-chart-grid
When to use
- A single value against a range with a needle and threshold zones
- Dashboard KPIs where a speedometer metaphor aids quick reading
When not to use
- Several progress values — use RadialBar
- A simple bar against thresholds — use Meter
Examples
Speedometer with zones
import { Gauge } from '@cascivo/charts'
<Gauge
title="CPU load"
value={72}
unit="%"
thresholds={[
{ upTo: 50, color: 'var(--cascivo-chart-2)' },
{ upTo: 80, color: 'var(--cascivo-chart-3)' },
{ upTo: 100, color: 'var(--cascivo-chart-4)' },
]}
/>