Meter
min–max scale: one value, a band, a head-to-head split or named shares, with optional
threshold ticks. It shares the track, sizes and colours of ProgressBar, but it
measures; it does not report task progress.When to use
- A static measurement on a known scale: a score, possession, a tallied percentage.
- A band (min–max) or two sides compared against a threshold.
- One quantity split into a few named shares (tokens by layer, cost by phase).
- Task progress (upload, loading) — use
ProgressBar. - A trend over time — use
Sparkline. - More than five or six shares, or values a reader must compare precisely — use a table.
Usage
import { Meter } from '@apollion-dsi/core/data-display/meter';
<Meter label="Ball possession" value={58} color="success" border />;label is required: it names the bar. With value, the fill runs from min to the value.
Bands and head-to-head
segments paint ranges of the scale. Without value, one segment highlights a band. A segment's color is a raw CSS
colour, for runtime data such as a team palette; ticks mark thresholds.
<Meter label="Score band 61 to 84" max={99} segments={[{ from: 61, to: 84 }]} />
<Meter label="Head-to-head: home 62%, away 38%" segments={sides} ticks={[{ at: 50 }]} />Stacked shares
shares stacks named parts of one quantity from min, in order. Each share paints a theme token, never a raw colour.
Hover or Tab to a share and a tooltip shows its label, amount (format, default toLocaleString('en-US')), its
percentage of the scale and its description. The scale is max, grown to fit the sum; without max the shares fill
the track. shares cannot be combined with value or segments (a type error).
<Meter
label="Tokens by layer"
max={15000}
shares={[
{ id: 'policies', label: 'Policies', value: 1200, color: 'tertiary', description: 'Conduct every run carries.' },
{ id: 'core', label: 'Persona + archetype', value: 2142, color: 'primary' },
]}
/>Accessibility
- With
value:role="meter"witharia-valuemin,aria-valuemaxandaria-valuenow. - Without
value(bands, head-to-head):role="img"named bylabel. Say the reading in the label. - With
shares:role="group"named bylabeland described by a summary of every share. Each non-empty share is a<button>namedLabel: amount (percent). Prefersize="medium"or larger so shares are easy pointer targets.
Properties
borderbooleanfalsecolor"primary""secondary""tertiary""success""warning""danger""neutral"'primary'format((value: number) => string)(value) => value.toLocaleString('en-US')label *stringnonemaxnumber100minnumber0segmentsMeterSegment[]nonesharesMeterShare[]nonesize"small""medium""large""extraSmall"'medium'ticksMeterTick[]nonevaluenumbernoneBeyond the props above, the component accepts the native
<div>attributes and the grid placement props (area,alignSelf,justifySelf).