Meter

Static measurement bar: min–max range, positioned segments and threshold markers. It is the data-viz primitive for "how much of this on a scale" — score band, head-to-head comparison, indicator with a target — that consumers used to reimplement with Flex + absolute positioning.

It shares the track, the size scale and the color contract of ProgressBar, but with its own semantics: measurement (role="meter"/role="img"), not task progress.

When to use

✅ Use when…	🚫 Avoid when…
To display a static measurement on a known scale (score, possession, tallied percentage). To highlight a band (min–max) or compare two sides (dual-fill) with a threshold. When the color comes from runtime data (per-team palette, band by range).	For in-flight task progress (upload, loading) — use `ProgressBar`. For an indeterminate state — use `Spinner`. For user value input — use `InputRange`.

Basic usage

import { Meter } from '@apollion-dsi/core/data-display/meter';
 
const Example = () => <Meter label="Ball possession" value={58} color="success" border />;

With value, the container takes role="meter" + aria-valuemin/max/now and the fill goes from min up to the value.

Band (min–max range)

A single segment highlights a band of the scale — without value, the container is descriptive (role="img" + aria-label):

<Meter label="Score band 61 to 84" max={99} segments={[{ from: 61, to: 84 }]} border />

Head-to-head (dual-fill + tick)

Segments accept raw CSS color — the use case is runtime data (per-team palette), which does not go through the theme palette. The tick marks the threshold:

<Meter
  label="Head-to-head record: Brazil 62%, opponent 38%"
  segments={[
    { from: 0, to: 62, color: '#009739' },
    { from: 62, to: 100, color: '#3B4CCA' },
  ]}
  ticks={[{ at: 50 }]}
/>

Properties


Prop	Type	Default	Description
`border`	`boolean`	`false`	Rounds the track edges (same behavior as the `ProgressBar`).
`color`	`"primary" \| "secondary" \| "tertiary" \| "success" \| "warning" \| "danger" \| "neutral"`	`primary`	Default semantic color (track + fill without its own color). Same scale as the `ProgressBar`.
`label *`	`string`	—	Accessible label of the measurement — becomes the container's `aria-label`. Required: the bar is graphical and without it there is no accessible name.
`max`	`number`	`100`	End of the scale.
`min`	`number`	`0`	Start of the scale.
`segments`	`MeterSegment[]`	—	Segments painted over the track, in scale units. They overlay the fill derived from `value`.
`size`	`"small" \| "medium" \| "large" \| "extraSmall"`	`medium`	Track height — same size scale as the `ProgressBar`.
`ticks`	`MeterTick[]`	—	Vertical threshold ticks, in scale units.
`value`	`number`	—	Measured value. When present, the container takes `role="meter"` with `aria-valuemin/max/now` and, without `segments`, paints the fill from `min` up to the value. Without `value`, the container is decorative-descriptive (`role="img"` + `aria-label`) — the band/dual-fill case.