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.

Upload progress
x

Installation

npx @yolkui/cli add progress

Done 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.

Uploading report.pdf
x
report.pdf uploaded
x
Upload failed: connection lost
x

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).

photos.zip
x

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.

Preparing your export…
x

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.

Downloading backup.zip
x

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.

x

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.

تقدم الرفع
x

API

Every part takes className and the props of its element. Progress takes the props of Base UI's Progress.

PropTypeWhat it does
valuenumber · nullOn Progress: how much is done. null for a task whose length is unknown.
min · maxnumberOn Progress: the range. 0 and 100 by default.
toneneutral · accent · success · info · warning · destructiveOn Progress: the fill's colour. neutral by default.
formatIntl.NumberFormatOptionsOn Progress: how the number is written, e.g. { style: "unit", unit: "megabyte" }.
localestringOn Progress: the language the number is written in. The browser's by default.
getAriaValueText(formatted, value) => stringOn Progress: what a screen reader hears for the value.
noncestringOn 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.
ProgressLabelspanThe name, linked to the bar.
ProgressValuespanThe value as text, a percentage by default; a function child writes your own.
ProgressTrack · ProgressIndicatordivThe 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.