Components

Gauge Chart

Put a measurement in context with a bounded scale and meaningful ranges. Keep the exact value visible, even when it goes beyond a limit.

Install

npx mario-charts@latest add gauge-chart

Playground

Explore live values, thresholds, and range limits.

Settings

The same gauge through every state.

PresetValue · 65%

StateEnd capsStroke width · 20px

Animate

CPU utilization

Illustrative measurement · 0 to 100%

Waiting for chart space

Hover, tap, or focus the gauge to inspect. Escape dismisses the tooltip. Change the value to see the arc update.

Usage

tsx

import { GaugeChart } from "@/components/charts/gauge-chart";

const zones = [
  { from: 0, to: 60, color: "#22c55e", label: "Normal" },
  { from: 60, to: 80, color: "#f59e0b", label: "High" },
  { from: 80, to: 100, color: "#ef4444", label: "Critical" },
];

export function Utilization() {
  return <GaugeChart value={65} zones={zones} unit="%"
    label="CPU utilization" ariaLabel="CPU utilization" height={360} />;
}

Reading the gauge

The arc shows position within the configured range, measured from the minimum. A range of 20–120 places 70 at the midpoint; this is not a percentage of the maximum.

The center and tooltip retain the actual measurement. Above or below the range, the arc stops at its endpoint and keeps the boundary zone’s color. A visible status explains why. The meter is read-only.

Zones include their starting value and exclude their ending value, except at the gauge maximum. A shared boundary belongs to the zone starting there. Gaps remain unclassified; overlapping zones produce an error.

Use thresholds that match your metric. A high value may be good for target attainment and bad for CPU pressure. Keep labels descriptive so color is not the only explanation.

API Reference

Typed props for values, ranges, zones, and inspection.

Prop	Type	Default	Description
`value`Required	number	—	Actual finite measurement. Outside-range values remain visible; the arc is clamped and retains the boundary zone color, with an Above range / Below range indication.
`zones`Required	readonly GaugeZone[]	—	Nonoverlapping { from, to, color, label? } regions inside the range. Zones may be unordered and share colors. Gaps remain unclassified; an empty list displays No Data.
`min / max`	number	0 / 100	Finite bounds with min < max. Signed ranges and nonzero minima are supported.
`unit / label`	string	—	Unit appended to the formatted measurement and a descriptive center label. Full text remains available through inspection.
`strokeWidth`	number	20	Positive requested stroke thickness in pixels; capped to fit small frames.
`strokeLinecap`	'round' \| 'butt'	'round'	Rounded or flat progress/track ends. Zone boundaries stay flat so adjacent regions do not overlap.
`height`	number	300	Stable positive frame height across ready, loading, empty, and error states.
`loading`	boolean	false	Retain the measurement and zones for matching skeleton geometry. Missing/invalid input uses a neutral placeholder.
`error`	string \| null	null	Actionable error message inside the persistent frame.
`animation`	boolean	true	Sweep from the minimum on entrance and animate updates from the current arc. Focus finishes motion immediately; reduced motion is respected.
`valueFormatter`	(value: number) => string	formatValue	Format the actual measurement, ranges, and inspection. Unit is appended separately.
`axisValueFormatter`	(value: number) => string	valueFormatter	Optional compact endpoint formatting.
`ariaLabel / description`	string	label or 'Gauge' / undefined	Accessible meter name and context. ARIA reports the actual measurement in value text and the bounded arc value numerically.
`tooltipRenderer`	TooltipRenderer<GaugeChartTooltipData>	—	Actual value, clampedValue, min/max, rangeStatus, bounded range-position percentage, unit/label, and the actual zone with original index.
`className`	string	—	Classes for the persistent outer frame.