When to use
- Multi-step flows where the user benefits from knowing how much is left (uploads, installations, form wizards).
- Long-running operations where a percentage or step count can be calculated.
- To indicate storage or data usage.
When to use something else
- Unknown duration: use Page loader / skeleton / shimmer patterns instead of a fake percentage.
- Very fast operations (under ~1s): skip the bar to avoid flicker.
- Decorative metrics: use charts or static labels, not a determinate progress bar.
Dos and don’ts
- Do pair with a label that describes what’s in progress — “Uploading files” is more useful than a bar alone.
- Do update the value in real time if possible; a static progress bar reads as broken.
- Don’t reset to 0 and run again to imply ongoing activity — use Page loader / indeterminate patterns for unknown completion.
- Don’t use multiple progress bars in close proximity unless each clearly maps to a distinct parallel operation.
Behavior
- If the operation can be canceled, provide a cancel action alongside the bar — not after it completes.
- Avoid showing a percentage if the underlying estimate is unreliable; or show a step indicator (“Step 2 of 4”) instead.
Often used with
Visible status label; optional cancel Button; pairs with File upload or long jobs.Visual examples
The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.Small
Use the small progress bar in compact rows, cards, or toolbars where a full-width bar would dominate the layout.Custom aria label
Provide a customaria-label when the visible label alone does not fully describe what is progressing—for example, “Uploading 3 of 10 files.”