Progress

Indicators

Open in Storybook: Progress (opens in a new tab)

Overview

The native progress tag is used for work that will finish: an upload, an import, a feed loading, a place in a queue. It has four parts: a label that names it, a value (value and max), a fill and a track. Fill and track are pseudo-elements, so the bar needs no wrapper, no inner div will be used for this component.

It is a semantic HTML element and every status, milestones and messages are handled natively. If we need to announce a status we will use ariaNotify().

It is not focusable and not a live region. In case we need to manipulate the progress we will have to have an interactive control associated to it.

Anatomy

Usage

Use cases

Functional elements where you can interact with different states, use cases and designs.

• One file uploading

  Determinate, in bytes.

  Uploading report.pdf68%68%Try it

  Said with ariaNotify(): nothing yet.

  Make it fail at 60%

  value="68" max="100"

  Done and failed in a status line. Offer cancel.

• Several uploads

  One named bar per file.

  3 files1 of 3

  • a.pdf
  • b.png
  • c.mov

  Try it

  One progress per file, the label is the file name

  An overall bar needs its own label.

• Importing contacts

  Unit is not percent.

  Importing contactsStep 3 of 8Step 3 of 8Try it

  Said with ariaNotify(): nothing yet.

  Make it fail at 60%

  value="3" max="8" aria-valuetext="Step 3 of 8"

  Same words visible and in aria-valuetext.

• Position in a queue

  Spots moved, not a percentage.

  Waiting in line28th · ~4 min28th · ~4 minJoin the queue

  Said with ariaNotify(): nothing yet.

  value="12" max="40" aria-valuetext="28th in line, about 4 minutes"

  Say the position and the wait in text.

• Loading the feed

  Indeterminate + aria-busy.

  Loading the feed

  Try it

  No value · aria-busy on the region

  Remove aria-busy when done.

• Sync of unknown length

  Indeterminate + text.

  Syncing your libraryTry it

  Said with ariaNotify(): nothing yet.

  No value · text says what is happening

  No invented percentages.

• Percent ring

  Same native element, painted.

  Backing up photos

  45%45%

  Try it

  Said with ariaNotify(): nothing yet.

  appearance: none · conic-gradient from --pct

  Visible number in an aria-hidden sibling.

• Profile completion

  Task completion, so progress.

  Profile complete60%60%

  Finish your profile

  Add a photoAdd a short bioLink your siteVerify your emailPick your language

  value="60" max="100"

  Label says complete what.

Props

Example

The words of message are what is said. Change them at the start, at a milestone and at the end, never on a tick.

import { Progress } from '@/components/Progress'

<Progress
  label="Uploading report.pdf"
  value={68}
  status="working"
  message="Uploading report.pdf"
>
  <button type="button" onClick={cancel}>Cancel</button>
</Progress>

Specs

Measurements

States

The element has no error, done or cancelled state, and the fill alone never says what happened: every state is said in words with an icon.

Layout

The breakpoints are container queries in rem, so they follow the room the field has and the size of the text: a field in a narrow card stacks on a wide screen. One DOM, only the CSS changes. Each use case is a story in Storybook. Pick the width in the viewport menu of the toolbar, for any story: 640 CSS px · 200% zoom or 320 CSS px · 400% zoom.

Attributes

No min: the scale always starts at 0. Indeterminate means one thing: value is absent. From script, progress.position is value ÷ max, or -1 when indeterminate; removeAttribute("value") makes it indeterminate again and progress.value = 0 writes value="0". In React pass value={undefined}, never value="".

Reading the markup

Markup

<label for="upload">Uploading report.pdf</label>
<span aria-hidden="true">68%</span>
<progress id="upload" value="68" max="100">68%</progress>
<p><svg aria-hidden="true" focusable="false">…</svg> Uploading report.pdf</p>
<button type="button">Cancel</button>

Styling

One rule for each engine: a selector list of both is dropped whole by each.

progress {
  appearance: none;                  /* first, or the rules below are ignored */
  display: block;
  box-sizing: border-box;
  inline-size: 100%;
  block-size: 0.75rem;
  border: 2px solid #5e548e;
  border-radius: 999px;
  background-color: #ebebec;         /* the track, in Firefox */
  print-color-adjust: exact;         /* the fill is a background */
}
progress::-webkit-progress-bar   { background-color: #ebebec; border-radius: 999px; }
progress::-webkit-progress-value { background-color: #5e548e; border-radius: 999px; }
progress::-moz-progress-bar      { background-color: #5e548e; border-radius: 999px; }

/* No value: a slice slides over the element, and both fills are see-through */
progress:indeterminate {
  background-image: linear-gradient(90deg, transparent, #5e548e, transparent);
  background-size: 40% 100%;
  background-repeat: no-repeat;
  animation: slide 1.4s linear infinite;
}
progress:indeterminate::-webkit-progress-bar,
progress:indeterminate::-webkit-progress-value { background: transparent; }
progress:indeterminate::-moz-progress-bar { background: transparent; }
@keyframes slide { from { background-position: -100% 0; } to { background-position: 200% 0; } }

@media (prefers-reduced-motion: reduce) {
  progress:indeterminate {
    animation: none;
    background-image: repeating-linear-gradient(45deg, #5e548e 0 0.5rem, transparent 0.5rem 1rem);
    background-size: auto;
  }
}

Across engines

Tokens

Component tokens

Guidelines

Alternatives

The spec calls progress “the wrong element to use for something that is just a gauge”. If a bar also appears next to a stepper, the stepper is the source of truth.

Content

Behavior

Accessibility

Rules

Keyboard

Roles and properties

Screen reader

Chromium’s accessibility tree for each markup, from the design. Listen in NVDA, JAWS and VoiceOver before trusting the milestone steps.

Announcements

A bar that moves is not a message. WCAG 4.1.3 covers the progress of a process, so the words are kept apart from the bar and say only what matters. They are the words of the status line, said once when they change; where ariaNotify is missing nothing is said and no live region replaces it. Every 25% is a starting point. Nothing here was heard in a screen reader yet.

Measured behavior

Chromium 148 and WebKit 26.4, from the design, 2026-10-16. The table of attributes was run again in Chromium here. Firefox rules are from MDN and untested.

Support

WCAG criteria

Related

This section is still in progress.

References

This section is still in progress.