Meter | Sodium design system

Kind

When to use it

Use: A level inside a known range: credits against a quota, a disk, a queue against its limit.
Use: The parts of one whole on one line, such as storage by table (MeterStack).
Not for: A task moving to done. Use Progress.
Not for: A value that changes over time; that is a chart.
Not for: A number with no range. Use Status strip.

7 rules

Must: Use Meter for a level and Progress for a task; never a Meter that counts up to done. Because role="meter" is read as a gauge, so a screen reader says "412 of 500" with no sense that anything finishes.
Must: Give every Meter a MeterLabel and a MeterValue. Because the yellow fill is 1.4:1 on white, so the reading is what carries the number; the bar only shows its shape.
Should: Set warnAt and failAt where the limit actually bites; null when the range has no trouble in it.
Never: Colour the fill by hand; pass warnAt and failAt, or status words through statusLabel. Because a hand-set red drops the word that says why, and the screen reader never hears it.
Must: Give MeterStack at most six parts and fold the rest into one "Other" part. Because there are six data colours, and a seventh part is dropped from the line.
Must: Keep the MeterStack key unless a table beside it lists every part with its value. Because the parts differ by colour alone on the line, and the key is where each one gets its name and number.
Should: Format the reading with its unit in MeterValue's children, as written: "412 / 500", "82%".

3 states, highest first

4 checks

: role="meter" with aria-valuetext that adds the status words: "92%, Near limit".
: The track edge is the control edge, 3.7:1 on white and 3.6:1 on the dark page, so the range reads whatever the fill.
: The sodium fill is 1.4:1 on white and never the only cue: the reading and its words carry the value.
: MeterStack is a named group; its line is aria-hidden and its key lists every part as text.

6 edge cases

Value past max: The fill stops at the end of the track; the reading still says the real number.
Zero: The track shows empty with its edge; the reading says 0.
A tiny stack part: Keeps 2px on the line so it is not lost; its exact value is in the key.
Narrow column: The label truncates; the reading never does.
Reduced motion: The fill moves to its width at once.
Forced colours: The fill and parts draw in CanvasText inside a CanvasText edge.

7 props

value, min, max: number default 0 to 100
size: 'default' | 'sm' default 'default'
warnAt: number | null default 0.8
failAt: number | null default 1
statusLabel: ReactNode default 'Near limit' | 'At limit'
MeterValue children: (formatted, value) => ReactNode
MeterStack parts, max, label: {label, value, display?}[], number, string

16 tokens