Skip to the content

Meter

A static measurement bar on a 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.
Data Display

When to use

Use when
  • 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).
Avoid when
  • 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).

Policies 1,200, Persona + archetype 2,142. Total 3,342 of 15,000.
<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" with aria-valuemin, aria-valuemax and aria-valuenow.
  • Without value (bands, head-to-head): role="img" named by label. Say the reading in the label.
  • With shares: role="group" named by label and described by a summary of every share. Each non-empty share is a <button> named Label: amount (percent). Prefer size="medium" or larger so shares are easy pointer targets.

Properties

Beyond the props above, the component accepts the native <div> attributes and the grid placement props (area, alignSelf, justifySelf).

See also