Gauge

A 240° arc meter for single-value utilization readouts — occupancy, load, capacity — with threshold ticks and automatic tone derivation.

Import

import { Gauge } from "@roger-emerson/ploxum-primitives";

Usage

<div className="flex items-end gap-6">
  <Gauge
    label="Hall A occupancy"
    showValue
    size={72}
    thresholds={{ warning: 0.75, critical: 0.9 }}
    unit="%"
    value={0.82}
  />
  <Gauge
    label="Gate 4 throughput"
    showValue
    size={72}
    thresholds={{ warning: 0.75, critical: 0.9 }}
    unit="%"
    value={0.47}
  />
</div>

Props

Prop	Type	Default	Description
`value`	`number`	—	Fill `0..1` — values outside the range are clamped. Required.
`size`	`number`	`64`	Gauge size in px.
`stroke`	`number`	`6`	Arc stroke width in px.
`thresholds`	`GaugeThresholds`	—	`{ warning, critical }` as `0..1` fractions. Tick marks render at these positions; tone derives when crossed.
`tone`	`"ok" \| "warning" \| "critical"`	derived	Explicit tone — wins over threshold derivation.
`label`	`string`	`"Capacity {pct}%"`	Accessible label. Also rendered beneath the arc when set.
`showValue`	`boolean`	—	Show the percentage in the center (mono, tabular numerals).
`unit`	`string`	—	Unit suffix shown after the center value.
`className`	`string`	—	Merged onto the wrapper.
`ref`	`Ref<SVGSVGElement>`	—	Ref to the inner `<svg>`.

interface GaugeThresholds {
  /** 0..1 fraction at which the gauge derives the warning tone. */
  warning: number;
  /** 0..1 fraction at which the gauge derives the critical tone. */
  critical: number;
}

The wrapper carries role="meter" with aria-valuenow/aria-valuemin/aria-valuemax — no extra ARIA needed.

Design rules

Threshold ticks are the non-hue signal. When thresholds drive the tone, never remove or restyle them — color-blind operators read position, not hue.
A StatusPip renders in the center whenever the tone leaves ok, so state reads by shape + color, never hue alone.
The fill transition (250ms) self-disables at critical tone and under prefers-reduced-motion — critical state renders instantly and motionless per heuristic 3.
Arc ends use strokeLinecap="butt" (blunt flat-cut, matching the Reticle mark). Don't round them.

Storybook

Open Gauge in Storybook ↗