Progress | Sodium design system

Sizes

When to use it

Use: A task with a known end moves toward it: a backfill over partitions, an export, an index build.
Use: A task with no known end yet (value null), until the first count arrives.
Not for: A level inside a range, such as a quota. Use Meter.
Not for: Where a job stands rather than how far. Use Status.
Not for: A button waiting on its own action. Use Button.

6 rules

Must: Give every Progress a ProgressLabel and a ProgressValue. Because the cells show a shape, and the reading is what says how many are left.
Must: Pass value={null} until the first count arrives; never 0 for unknown. Because 0 reads as "nothing done", and the pending mark is what says "working, count not known yet".
Never: Fill a Progress in the sodium yellow. Because yellow is the action and the first data series; a task is work, so it is ink, and a yellow bar beside the slab reads as a second action.
Must: Show a task in trouble with status="fail" or "warn", which brings its word; never a red fill alone. Because hue alone vanishes in grayscale, and the status word joins what a screen reader hears.
Never: Add a spinner or a sweeping bar beside an indeterminate Progress. Because its reading already shows the pending mark, the one loop Sodium allows.
Should: Show one Progress per task the person started; roll many small tasks into one count.

5 states, highest first

3 checks

: role="progressbar" with aria-valuetext that adds the status word: "50%, Failed"; indeterminate reads "In progress".
: The done cells are ink on the empty rule-coloured cells, 13.7:1 in light; the reading text-1 on the page, 18.3:1.
: The pending mark in the reading is aria-hidden; the role already says the task is working.

5 edge cases

Value past max: Every cell fills; the reading says the real count.
Partial cell: The last done cell may be cut part way; the reading carries the exact count.
Right to left: The cells run from the right edge and fill toward the left.
Reduced motion: The fill moves at once and the pending mark stands still with its first cell lit.
Forced colours: Done cells draw in CanvasText over GrayText cells.

5 props

13 tokens