Progress
How much of a task is done, as a bar with a label and a value; a sliding piece when nobody knows how long.
Installation
npx @yolkui/cli add progressDone and failed
The bar stays neutral while the task runs. When the page knows how it ended, it sets tone: success for a finished task, destructive for one that stopped, and the label of a failed bar turns red as well. Say it in the label too ("report.pdf uploaded", "Upload failed"), so the colour is never the only sign. The bar never turns green on its own at 100%: a full bar is not always good news.
Updating the value
Progress shows the value it is given; the page moves it. The fill grows smoothly to each new value (at once under reduced motion).
When nobody knows how long
value={null} means work is going on but its length is unknown: a third of the bar slides from the start to the end. Leave ProgressValue out, or it stays empty. Under reduced motion the piece stays in the middle and slowly fades in and out instead of travelling.
Your own range and words
min and max set the range (0 to 100 by default). ProgressValue writes the value as a percentage; a function child writes your own text, and getAriaValueText gives a screen reader the same words. format and locale on Progress change how the number is written.
Just the bar
Without ProgressLabel, name the bar with aria-label. Without a name a screen reader hears only "progress bar, 33%", and in development the console warns.
Right to left
Under dir="rtl" the bar fills from the right and the value moves to the left on their own. locale writes the digits the page's way.
API
Every part takes className and the props of its element. Progress takes the props of Base UI's Progress.
| Prop | Type | What it does |
|---|---|---|
value | number · null | On Progress: how much is done. null for a task whose length is unknown. |
min · max | number | On Progress: the range. 0 and 100 by default. |
tone | neutral · accent · success · info · warning · destructive | On Progress: the fill's colour. neutral by default. |
format | Intl.NumberFormatOptions | On Progress: how the number is written, e.g. { style: "unit", unit: "megabyte" }. |
locale | string | On Progress: the language the number is written in. The browser's by default. |
getAriaValueText | (formatted, value) => string | On Progress: what a screen reader hears for the value. |
nonce | string | On Progress: your Content-Security-Policy nonce, for a site that blocks styles written into the page; it lets the indeterminate animation load. Without it such a site shows the piece still, in the middle of the bar. |
ProgressLabel | span | The name, linked to the bar. |
ProgressValue | span | The value as text, a percentage by default; a function child writes your own. |
ProgressTrack · ProgressIndicator | div | The bar and its fill. Progress adds them after its children. |
Accessibility
Progress is a progressbar with its value, minimum and maximum, from Base UI.
- ProgressLabel names the bar through aria-labelledby; without it, pass aria-label. In development the console warns when the bar has no name.
- A screen reader does not announce every change of the value. When the task ends, say so in a place that is read aloud, such as a Toast, or move focus to what comes next.
- An indeterminate bar has no value; Base UI gives it the words "indeterminate progress". getAriaValueText translates them, with the rest of the page.
- Progress is for a task that moves toward its end. A level that only is what it is (storage used, battery, a password's strength) is a meter, a different role for a screen reader.
- The fill keeps 3:1 against the track and the page in every tone and both themes; the tone is also said in the label. In Windows High Contrast the bar keeps an outline and its fill.
- When the system asks for reduced motion the fill jumps to each new value and the indeterminate piece stops travelling: it stays in the middle and fades in and out, so it still shows that work is going on.