Progress

Usage

Overview

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

When to use

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".

When not to use

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.

Content guidelines

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.

Behavior and states

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.

Best practices

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.

Accessibility

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.

Loading indicator for indeterminate work.
Skeleton for placeholder content.
Snackbar for completion messaging.

Accessibility / Screen Reader Testing

Progress / API and Development

On this page

Overview

When to use

When not to use

Determinate vs. indeterminate

Progress

Usage

Overview

Uploading radio dialogue

When to use

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".

When not to use

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.

Content guidelines

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.

Behavior and states

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.

Best practices

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.

Accessibility

Loading indicator for indeterminate work.
Skeleton for placeholder content.
Snackbar for completion messaging.

Accessibility / Screen Reader Testing

Progress / API and Development

On this page

Overview

When to use

When not to use

Determinate vs. indeterminate