Progress communicates how much of an operation is complete or—when unknown—that work is actively underway. It reduces perceived latency during uploads, saves, and batch jobs, and it rescues operators from concluding that a slow process has frozen. The mental model is "time and work remaining", grounded in real percentages whenever true data exists.
Uploading radio dialogue
64%
- File upload or download with byte-level or step-level progress.
- Batch and import jobs where operators must know completion is advancing.
- Multi-step flows with discrete, trackable stages.
- Any operation that takes more than a brief moment—silence reads as "frozen".
- Instant operations under a few hundred milliseconds—prefer subtle UI or nothing at all.
- Indeterminate busy states where a
LoadingIndicator or Skeleton is the established pattern.
- Workflow status that is not a single running task—use badges, timeline, or list state.
Determinate vs. indeterminate
- Determinate (
value). Use whenever true data exists. Round sensibly; avoid oscillating numbers from noisy estimates.
- Indeterminate (animation). Use honestly; do not imply precision you don't have. Animate until the operation resolves.
- With label. Names the task ("Uploading incident_audio.wav" beats "Uploading"). Present tense, verb-led.
- Percentage. Show when the number genuinely helps; hide when it flickers or misleads.
- Labels are short and specific; localize via
formatMessage.
- Completion moves to 100% when work is truly done; follow with next-step guidance or success feedback.
- On error, transition cleanly to an error message. Don't leave the bar stuck near complete.
- Updates. Smooth monotonic increases for determinate bars; debounce noisy streams.
- Reset. Clear or hide the bar when a new operation starts so operators don't confuse jobs.
- Multiple operations. Separate bars per operation, or one aggregate with a clear explanation—never an ambiguous blend.
- Cancellation. When operators can cancel, place the control near the progress region.
Do
- Prefer real
value over simulated duration when instrumentation exists.
- Place the bar adjacent to the content it describes.
- Pair long waits with an estimated time only when the estimate is reliable.
Don't
- Show false precision (jumping 10% chunks) on animation meant purely to reassure.
- Reuse the same progress region for unrelated tasks without resetting state.
- Block the whole app for progress that only affects one card, unless strictly necessary.
role="progressbar" with aria-valuenow / aria-valuemin / aria-valuemax when determinate; indeterminate state exposed explicitly. Label text is available as accessible name or description. See Accessibility for the full contract.
