Charts

Gauge

A minimal arc gauge showing where a value sits in a range with optional threshold zones and target marker.

import { Gauge } from "metricui";

Use Gauge when you need to show a single value's position within a range — CPU usage, NPS score, budget utilization, or any metric with clear min/max bounds. For simple numeric KPIs without a range context, use KpiCard instead.

Basic Example

CPU Usage

<Gauge
  value={73}
  title="CPU Usage"
  format="percent"
/>

Thresholds

Pass a thresholds array to color zones on the arc. Each threshold defines a start value and color. The fill arc auto-picks the color of the zone the current value falls in.

CPU Usage

<Gauge
  value={73}
  title="CPU Usage"
  format="percent"
  thresholds={[
    { value: 0, color: "#10b981" },
    { value: 60, color: "#f59e0b" },
    { value: 85, color: "#ef4444" },
  ]}
/>

Target & Comparison

Add a target tick mark on the arc and a comparison badge below the gauge to show period-over-period change.

Budget Utilization

+16.0%vs last quarter

<Gauge
  value={67500}
  min={0}
  max={100000}
  title="Budget Utilization"
  format="currency"
  target={80000}
  targetLabel="Target"
  comparison={{ value: 58200 }}
  comparisonLabel="vs last quarter"
/>

Arc Styles

Choose between 270° (default, gap at bottom) and 180° (semicircle) arcs using the arcAngle prop.

270° arc (default)

NPS Score

180° arc (semicircle)

NPS Score

// 270° arc (default)
<Gauge value={72} arcAngle={270} />

// 180° semicircle
<Gauge value={72} arcAngle={180} />

Data States

Every component handles loading, empty, and error states. Pass individual props or use the grouped state prop.

Empty

No data available

// Loading state
<Gauge value={undefined} title="CPU Usage" loading />

// Empty state
<Gauge value={undefined} title="CPU Usage" empty={{ message: "No data" }} />

Props

Prop	Type	Default	Description
`value`*	`number \| null \| undefined`	—	Current value. Pass null/undefined for null state display.
`min`	`number`	`0`	Minimum value for the gauge range.
`max`	`number`	`100`	Maximum value for the gauge range.
`title`	`string`	—	Title displayed above the gauge.
`subtitle`	`string`	—	Subtitle displayed below the centered value.
`description`	`string \| React.ReactNode`	—	Popover content for the ? icon next to the title.
`format`	`FormatOption`	—	Format for the centered value and min/max labels.
`comparison`	`ComparisonConfig \| ComparisonConfig[]`	—	Comparison badge(s) below the gauge.
`comparisonLabel`	`string`	—	Label for the primary comparison.
`thresholds`	`GaugeThreshold[]`	—	Threshold breakpoints for colored zones on the arc. Array of { value, color }.
`target`	`number`	—	Target marker rendered as a tick on the arc.
`targetLabel`	`string`	—	Label for the target marker.
`arcAngle`	`180 \| 270`	`270`	Arc sweep angle. 270° has a gap at the bottom, 180° is a semicircle.
`strokeWidth`	`number`	`12`	Thickness of the arc in px.
`color`	`string`	`var(--accent)`	Fill arc color. If thresholds provided and no color, auto-picks from threshold zone.
`showMinMax`	`boolean`	`true`	Show formatted min/max labels at arc endpoints.
`showValue`	`boolean`	`true`	Show the large centered value text.
`icon`	`React.ReactNode`	—	Icon next to the title.
`size`	`number`	`200`	SVG viewBox size in px.
`variant`	`CardVariant`	—	Card variant (supports custom strings). CSS-variable-driven via [data-variant]. Reads from MetricProvider.
`dense`	`boolean`	—	Compact padding. Reads from MetricProvider.
`animate`	`boolean \| AnimationConfig`	—	Animate arc fill and count-up. Reads from MetricProvider.
`nullDisplay`	`NullDisplay`	—	What to show when value is null. Reads from MetricProvider.
`loading`	`boolean`	—	Show skeleton placeholder.
`empty`	`EmptyState`	—	Empty state config.
`error`	`ErrorState`	—	Error state config.
`stale`	`StaleState`	—	Stale data indicator.
`className`	`string`	—	Additional class names for the outer card.
`classNames`	`{ root?: string; arc?: string; value?: string; title?: string }`	—	Sub-element class overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id for testing frameworks.
`drillDown`	`boolean \| ((event: { value: number; title: string }) => React.ReactNode)`	—	Enable drill-down on gauge click. `true` auto-generates a detail panel. Pass a render function for full control over the panel content. Requires DrillDown.Root wrapper.
`drillDownMode`	`DrillDownMode`	`"slide-over"`	Presentation mode for the drill-down panel. "slide-over" (default) slides from the right, full height. "modal" renders centered and compact.

Notes

Uses partial arc rendering for gauge display.
When thresholds are provided and no explicit color prop, the fill arc auto-picks the color of the zone the current value falls in.
The 270° arc has a ~90° gap at the bottom. The 180° arc is a semicircle with a flat bottom.
Uses role='meter' with aria-valuenow/min/max for accessibility.
Fill animation uses CSS strokeDashoffset transition, duration derived from motionConfig.

Playground

Experiment with every prop interactively. Adjust the controls on the right to see the component update in real time.

Live Preview

CPU Usage

Code

<Gauge
  value={73}
  title="CPU Usage"
  subtitle="avg. last 5 min"
  format={{ style: "percent" }}
  thresholds={[
    { value: 0, color: "#10b981" },
    { value: 60, color: "#f59e0b" },
    { value: 85, color: "#ef4444" },
  ]}
/>

Props

Adjust props to see the gauge update in real time

value

min

max

title

subtitle

format.style

How the value is displayed

arcAngle

Arc sweep angle

strokeWidth

Thickness of the arc

color

showMinMax

Min/max labels at arc ends

showValue

Centered value text

size

SVG viewport size in px