ProgressBar
Visualizes the completion status of a task, such as file uploads, multi-step flows, or background processing. Built on Base UI Progress , which renders role="progressbar" with aria-valuenow/aria-valuemin/aria-valuemax wired automatically.
Preview
Examples
Value
value sets the current progress. By default it is interpreted against a 0–100 range, but you can adjust the bounds with min and max. Pair it with showValue to display the formatted value next to the label.
| Prop | Type | Default | Description |
|---|---|---|---|
value | number | null | null | Current value. null renders an indeterminate bar. |
min | number | 0 | Minimum value. |
max | number | 100 | Maximum value. |
Indeterminate
When the progress is unknown (e.g. waiting on a network response with no measurable percentage), pass value={null}. The bar animates continuously and aria-valuenow is omitted.
Size
Controls the height of the bar.
| Value | Default | Description |
|---|---|---|
small | For dense layouts or inline progress. | |
medium | ✓ | Most versatile size. |
large | When the progress is a primary focal point. |
Intent
Controls the color of the progress indicator.
| Value | Default | Description |
|---|---|---|
primary | ✓ | General-purpose progress. |
secondary | Secondary or supplementary progress. | |
success | Completion or positive outcome. | |
warning | Progress that requires caution. | |
danger | Failing or at-risk progress. | |
neutral | Low-emphasis, neutral progress. |
Custom format
By default showValue renders a percentage. Pass formatValue to customize the displayed text — it also drives aria-valuetext, so screen readers announce the same value.
Guidelines
Determinate vs indeterminate
- Determinate (
valueis a number): use when you can measure progress, such as upload byte counts or completed steps. - Indeterminate (
value={null}): use when progress cannot be measured. Avoid leaving an indeterminate bar on screen indefinitely — switch to a determinate bar or a result state as soon as you can.
Accessibility
The label prop is required. The WAI-ARIA progressbar role mandates an accessible name, so label is both rendered as visible text and used as the accessible name. When customizing the value text with formatValue, keep it concise so the screen-reader announcement stays clear.