Progress bar

Usage

Use a progress bar for tasks that take more than a couple of seconds and whose progress you can measure: uploading inspection photos, importing a vehicle CSV, generating a monthly cost report. Use the indeterminate state when the total is unknown.

• For measurements that aren't progress (tank level, disk usage) use a meter. For short waits under ~2s, a spinner; for loading page content, a skeleton.
• Always pair the bar with a visible label naming the task and text stating progress ("12 of 20 photos"). On completion or failure, change the text too, not just the color.

Anatomy

1. Label — <label class="progress__label" for> naming the task
2. Value — .progress__value, percentage in tabular numerals
3. Track and fill — native <progress class="progress__bar">
4. Hint — .progress__hint, counts or the outcome, with an icon on complete/error

Examples

<div class="progress">
  <div class="progress__header">
    <label class="progress__label" for="pb-photos">Uploading inspection photos</label>
    <span class="progress__value" aria-hidden="true">60%</span>
  </div>
  <progress id="pb-photos" class="progress__bar" max="100" value="60" aria-describedby="pb-photos-hint">60%</progress>
  <p class="progress__hint" id="pb-photos-hint">12 of 20 photos</p>
</div>

<!-- Indeterminate: omit value -->
<progress class="progress__bar" max="100">Importing…</progress>

<!-- Outcome: tone + text; announce once -->
<div class="progress" data-state="complete | error">… <p class="progress__hint" role="status | alert">…</p></div>

API

Do and don't

Accessibility

• Role: native <progress> exposes progressbar with its value; indeterminate exposes no value. Name it with a <label for> (or aria-label for the thin bar).
• The visible percentage is aria-hidden because the bar already announces it; the hint is linked with aria-describedby.
• Don't announce every percent. Announce the outcome once: role="status" on completion, role="alert" on failure.
• The bar is not focusable and has no keyboard interaction.
• Contrast: fill (--color-action-primary-bg, success and danger icon colors) is ≥ 3:1 against the surface. Reduced motion stops the indeterminate sweep; the hint text still says what's happening.
• Forced colors: the track gets a border and the fill uses Highlight.

Tokens