Skip to content
EspañolEnglish
All components (204)

Progress

Surfaces · Progress

What it is and when to use it

Progress bar for a task that advances and ends: uploading a file, importing customers, processing an order. With indeterminate when it is not known how much is left.

When to use it

  • Tasks with an end: value goes from minValue to maxValue (0 and 100 by default).
  • withPercent writes the progress beside it, in the language's format ("42%"); formatOptions or valueLabel ("3 of 7") if the percentage does not fit.
  • indeterminate when there is no way of knowing how much is left: a bar that goes back and forth, never an invented percentage.
  • hiddenLabel when the text beside it already says what is advancing: it is still named the same for whoever cannot see the bar, but it is not drawn twice.
  • tone for the bar's color (success when done, error if it failed); color alone is not enough, the text has to say it too.

When not to

  • A level that is just there, whether it goes up or down (space used, stock): Gauge.
  • How much of a page has been read: ReadingProgress.
  • A button's wait: Button with loading.
  • The phases of a process: Steps.

Keyboard: it is not focusable.

Accessibility: it is its own <div role="progressbar"> (the native <progress> cannot be styled) with label as its name and aria-valuenow and aria-valuetext, so whoever cannot see the bar also knows how far along it is. The label says WHAT is advancing ("Uploading the invoice"), not "Progress". The indeterminate one carries no aria-valuenow. With reduced motion the indeterminate bar does not stop, it goes more slowly: it says that something is happening, it is not decoration.

Fine-tuning: --amset-progress-duration, how long one pass of the indeterminate bar takes (two turns of --amset-duration-spin, with --amset-easing-standard). The rest, with the classes amset-progress, amset-progress--sm (4 px track instead of 8) and amset-progress--indeterminate. The fill is --amset-accent if it has no tone.

Context: the percentage is written in the language of LocaleProvider (or AmsetProvider).

What it looks like

Uploading the invoice42%
Importing customers62%
Processing the order on the server
Uploading the delivery noteUpload failed

<Progress label="Uploading the invoice" value={42} withPercent />
<Progress label="Importing customers" value={310} maxValue={500} withPercent />
<Progress label="Processing the order on the server" indeterminate />
<Progress label="Uploading the delivery note" value={62} tone="error" withPercent valueLabel="Upload failed" />

Props

Import it with import { Progress } from '@amset/ui'. Required props are marked.

PropTypeWhat it does
labelrequiredstringWhat is happening. "Uploading the invoice", not "Progress".
aria-describedbystringIdentifies the element (or elements) that describes the object.
aria-detailsstringIdentifies the element that provides a detailed, extended description for the object.
aria-labelledbystringIdentifies the element (or elements) that labels the current element.
classNamestringMerged with the library classes; it does not replace them.
formatOptionsIntl.NumberFormatOptionsHow the value is written. By default, as a percentage.
hiddenLabelbooleanThe label is spoken but not painted: for when next to it it already says what is advancing ("Uploading, 62 %") and repeating it below only takes up space.
idstring—
indeterminatebooleanWhen it is not known how much remains: neither `aria-valuenow` nor a written percentage.
maxValuenumber—
minValuenumber—
size"sm" | "md"—
tone"neutral" | "accent" | "secondary" | "tertiary" | "info" | "success" | "warning" | "error"The colour of the bar: `success` when it ends well, `error` if it failed, `warning` if it has problems. Without a tone it is accent. Colour is NOT the only thing that says it (it cannot be read with a colour filter or a screen reader): put it in the text too (`valueLabel`: "Upload failed").
valuenumberHow much has been done. 0 by default, and it is clamped between the minimum and the maximum.
valueLabelReactNodeThe already-written value, if the automatic format does not fit ("3 of 7").
withPercentbooleanShows the percentage beside it. Not shown with indeterminate progress.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: