Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Meter

A horizontal capacity bar with threshold ticks, optional segmentation, and automatic tone escalation — the linear sibling of Gauge.

Import

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

Usage

<div className="flex w-64 flex-col gap-3">
  <Meter
    label="Queue depth — Gate 2"
    showValue
    thresholds={{ warning: 0.7, critical: 0.9 }}
    value={0.78}
  />
  <Meter
    label="Radio channels in use"
    segments={8}
    showValue
    size="sm"
    value={0.625}
  />
</div>

Props

PropTypeDefaultDescription
valuenumber—Percentage 0..1 — values outside the range are clamped. Required.
labelstring—Accessible label. Rendered visibly above the track when showValue is set. Required.
tone"amber" | "ok" | "warning" | "critical""amber"Base fill tone. Threshold derivation escalates past it when crossed.
thresholdsMeterThresholds—{ warning, critical } as 0..1 fractions. Derives the tone and renders tick marks on the track.
showValueboolean—Show the label and percentage above the track.
segmentsnumber—Divide the track into evenly-spaced segments with tick marks.
size"sm" | "md""md"Track height: sm = 4px, md = 6px.
classNamestring—Merged onto the root.
refRef<HTMLDivElement>—Ref to the root.
interface MeterThresholds {
  /** 0..1 — at or above this the meter renders warning. */
  warning: number;
  /** 0..1 — at or above this the meter renders critical. */
  critical: number;
}

The root carries role="meter" with aria-valuenow/aria-valuemin/aria-valuemax.

Design rules

  • Threshold ticks are a non-hue signal — they sit on the track at the warning/critical positions in their own tones. Never remove them when thresholds drive the fill color.
  • A StatusPip shape marker renders automatically whenever the resolved tone is warning or critical (beside the value when showValue, beside the track otherwise) — the same shape grammar as Gauge, so status never rides on hue alone.
  • The width transition (250ms) self-disables at critical tone and under prefers-reduced-motion — critical fills snap, motionless per heuristic 3.
  • Use segments for discrete capacity (radio channels, dock doors, gate lanes) so operators count units instead of estimating percentages.
  • label is required even without showValue — the meter is always AT-readable.

Storybook

Open Meter in Storybook ↗