Progress
FreeShow how far a task has come: an upload, an import or a run of setup steps.
npx wunderui-cli add progressPlayground
Installation
npx wunderui-cli add progressWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Progress,
ProgressIndicator,
ProgressLabel,
ProgressRow,
ProgressTrack,
ProgressValue,
} from "@/components/ui/progress"
import type {
ProgressRowProps,
ProgressValuePosition,
} from "@/components/ui/progress"Then use it:
import { Progress, ProgressLabel } from "@/components/ui/progress"
export function Upload() {
return (
<Progress value={50} valuePosition="right">
<ProgressLabel>Uploading report.pdf</ProgressLabel>
</Progress>
)
}Expected result: You should see the label Uploading report.pdf above a bar that is half full, with 50% at its right.
When to use
Use Progress for
- A task that runs to completion and whose progress you know, such as an upload or an import
- A run of steps, such as a setup checklist, with the count of steps done as the value
- A queue where every item has its own bar and its own status
Types
The value is printed at the right or left of the bar, below it, or in a bubble that follows the end of the fill. Without a value position the bar stands alone and needs an aria-label.
Content
A visible label names the task, so a screen reader and a sighted reader get the same name. Put the value beside the label, at the right of the bar or below it.
Range and format
A bar runs from min to max, 0 to 100 by default, and prints its value as a percent of that range. Set max to count steps, and format the value to print a size or your own text.
States
A bar is in progress, complete when the value reaches max, or indeterminate when nobody knows how far it has come. Indeterminate draws no fill and no value.
Row
ProgressRow is one line of a breakdown, such as a rating distribution or the share of each channel: the label at the start (with an optional icon), an 8 px bar that fills to value, and the share at the end. valueText replaces the percentage, for example with a review count, and tone switches the fill between the brand indigo and the yellow of a rating. The row reads as one image whose name is label and end text, or aria-label. It replaces HistogramBar.
Behavior and motion
What the bar does itself, and what it leaves to the page.
- Role and value
- Progress is a progressbar with a min (default 0), a max (default 100) and the value clamped to that range. The announced text is a percent of the range by default; you can replace it.
- Accessible name
- The bar has no name of its own: a label inside it becomes the name, and without one you pass an aria-label. The value part is hidden from assistive technology, so it is never the name.
- Indeterminate
- A null value marks a bar whose progress is unknown. The fill has no width and nothing moves, so show activity another way, with a Spinner or a message.
- Complete
- When the value reaches the max, the parts are marked complete; below it, progressing. The bar does not change colour: say that the task is done in the label.
- Size and tone
- One size and one tone: the track is 6 px high and fully rounded, and the fill uses the brand colour. There is no error variant, so tell a failure in words next to the bar.
- Value position
- With a value position the value sits in a 40 px column right or left of the track, below it, or in a dark bubble that follows the fill. The bubble is hidden from assistive technology.
- Motion
- When the value changes the fill glides over 700 ms and only the transform moves; the first render draws it at its value without moving. The bubble moves to its new place at once.
- Reduced motion
- With reduced motion the fill jumps to its new value. Colour changes stay.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- 1data-slot="progress"
The root: a progressbar with its min, max and current value set, and children such as the label render above the bar. The value can sit right or left of the bar, below it, or in a bubble.
- 2data-slot="progress-label"Optional
Names the task, and Progress points to it as its label. Without a label, give Progress an aria-label.
- 4data-slot="progress-track"Optional
The grey bar behind the fill: 6 px high and fully rounded. Progress already renders it; you only need it for a custom layout.
- 3data-slot="progress-indicator"Optional
The fill, in the brand colour, drawn at full width and scaled to the value so it glides to a new one. Progress already renders it; with a null value it has no width.
- 5data-slot="progress-value"Optional
Prints the formatted value, a percent of the range by default, in tabular figures. It is hidden from assistive technology, because the bar already announces its value.
- data-slot="progress-bubble"
- Optional
- data-slot="progress-row"Optional
One line of a breakdown, such as a rating distribution or the share of a channel: the label with an optional icon, an 8 px bar and the share at the end. The row reads as one image. It replaces HistogramBar.
- Optional
Best practices
- Do
Name the bar with a label, such as Uploading report.pdf. Screen readers then say what is progressing, not only the number.
- Do
Add the value part when the number matters. It formats the value in tabular figures, so the text does not jump while it counts.
- Do
Put the value where it is read first: right for a compact row, bottom when the bar spans the full width, or a bubble when the number should follow the end of the fill.
- Do
Set the max to the number of steps when the task has steps, and pass the steps done as the value, such as 3 of 5. The bar then needs no sum of its own.
- Do
When you print your own text, also pass a value text for screen readers, such as 3 of 5 steps. Otherwise it announces the percent.
- Do
Say a failure in words next to the bar and offer the next action, such as Failed, retry. The bar keeps the value where the task stopped.
- Don’t
Don't animate the width of the fill yourself. The indicator already scales smoothly.
- Don’t
Don't use an indeterminate bar for a long wait on its own. It draws no fill and no motion, so pair it with a Spinner or a message.
- Don’t
Don't show a bar for a measured value such as storage used, since it would announce a task that is never finished. Use Meter.
API reference
Every part also takes the props of the primitive it wraps, the Base UI Progress. The tables list what the page uses; aria props reach the element. ProgressRow is a plain div and takes only the props listed under it.
The root: a progressbar with its min, max and current value set, and children such as the label render above the bar. The value can sit right or left of the bar, below it, or in a bubble.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | null | — | How far the task has come, between and . A value outside the range is clamped. marks the bar indeterminate: it has no and draws no fill. |
| min | number | 0 | The value at which the bar is empty. The default is 0. |
| max | number | 100 | The value at which the task is complete. The default is 100. Set it to the number of steps to count steps. |
| valuePosition | "left" | "right" | "bottom" | "tooltip-top" | "tooltip-bottom" | — | Prints the value with the bar: or in a row with the track, below it, or in a bubble that follows the end of the fill. Leave it out to place yourself among the children. |
| format | Intl.NumberFormatOptions | — | options for the value. Without them the value is printed as a percent of the range; with them the clamped value itself is printed, as in . |
| locale | Intl.LocalesArgument | — | The locale for the formatted value, such as . The default is the locale of the browser. |
| aria-valuetext | AriaAttributes["aria-valuetext"] | — | Replaces the text a screen reader announces for the value. The default is the formatted value, or without a value. |
| getAriaValueText | (formattedValue, value) => string | — | Builds the announced text from the formatted value and the raw value, such as . It is called with as the value while the bar is indeterminate. |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state (, , ). |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline style for the part, an object or a function of the state. |
Names the task, and Progress points to it as its label. Without a label, give Progress an aria-label.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state (, , ). |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline style for the part, an object or a function of the state. |
The fill, in the brand colour, drawn at full width and scaled to the value so it glides to a new one. Progress already renders it; with a null value it has no width.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state (, , ). |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline style for the part, an object or a function of the state. |
The grey bar behind the fill: 6 px high and fully rounded. Progress already renders it; you only need it for a custom layout.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state (, , ). |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline style for the part, an object or a function of the state. |
Prints the formatted value, a percent of the range by default, in tabular figures. It is hidden from assistive technology, because the bar already announces its value.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | null | (formattedValue, value) => ReactNode | — | Replaces the printed text with your own. A function gets the formatted value (the word while the bar is indeterminate) and the raw value, for example . |
| render | ReactElement | (props, state) => ReactElement | — | Replaces the element of the part with another tag or component. Accepts an element or a function that returns one. |
| className | string | (state) => string | undefined | — | Extra classes, merged with the part's own. A string, or a function of the state (, , ). |
| style | CSSProperties | (state) => CSSProperties | undefined | — | Inline style for the part, an object or a function of the state. |
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — |
One line of a breakdown, such as a rating distribution or the share of a channel: the label with an optional icon, an 8 px bar and the share at the end. The row reads as one image. It replaces HistogramBar.
| Prop | Type | Default | Description |
|---|---|---|---|
| label required | ReactNode | — | The name of the row at the start, such as a star level or a channel. Required. |
| icon | ReactNode | — | A small mark after the label, such as a star. |
| value required | number | — | The share of the bar, 0 to 100. Values outside the range are clamped. Required. |
| valueText | ReactNode | — | Shown at the end instead of the rounded percentage, for example a review count. |
| tone | "primary" | "yellow" | "primary" | The fill colour: (default) or , the colour of a rating. |
| aria-label | string | — | The name of the whole row. By default it is built from the label and the end text. |
| className | string | — | Extra classes on the row. |
| Prop | Type | Default | Description |
|---|---|---|---|
| label required | ReactNode | — | The row's name, usually the star count (5). |
| value required | number | — | Share of the bar, 0 to 100 (clamped). |
| aria-label | string | — | Name of the whole row for assistive tech. Default: "5 stars: 78%", built from the label and the end text. |
| count | ReactNode | — | Shown at the end of the row instead of the rounded percentage (for example a review count). |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("progress")npx wunderui-cli add progressThe full library index for assistants is at /llms.txt.