Progress
Indicators
Open in Storybook: Progress (opens in a new tab)
Overview
The native progress tag is 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 and no inner div. It is not focusable, so to act on it we pair it with a control: Cancel, Pause or Retry.
The rule. The progress element is the semantics; a moving bar is not a message. Name it with a label, let ticks stay silent, and say “started”, “complete” and “failed” in a status line apart from the bar, once, with ariaNotify().
Anatomy
- Label
label forNames the bar. Always visible. “Progress bar” is not part of the name.
- Value text
span aria-hidden="true"The visible copy of the value. Hidden because the bar already exposes it.
- Track
progress,::-webkit-progress-barThe whole scale, 0 to
max. The element holds the role, the name, the value and the range. - Fill
::-webkit-progress-value,::-moz-progress-barThe part done. With no
valueit is absent and a slice slides over the track. - Status
pwith ansvgWhat the task is doing, in words and a shape. A change of its words is said once.
- Control
button type="button"Cancel, Pause or Retry: the keyboard story. Tab skips the bar and lands here.
Usage
Use cases
Eight common progress indicators, each the real component and each working.
One file uploading
Determinate, in bytes.
Said with ariaNotify(): nothing yet.
value="68" max="100"Done and failed in a status line. Offer cancel.
Several uploads
One named bar per file.
3 files
Said with ariaNotify(): nothing yet.
One
progressper file, the label is the file nameAn overall bar needs its own label. Each file that finishes is said once.
Importing contacts
Unit is not percent.
Said with ariaNotify(): nothing yet.
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.
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.Said with ariaNotify(): nothing yet.
No
value·aria-busyon the regionRemove
aria-busywhen done, and say it has loaded.Sync of unknown length
Indeterminate + text.
Said with ariaNotify(): nothing yet.
No
value· text says what is happeningNo invented percentages. Said when it ends.
Percent ring
Same native element, painted.
Said with ariaNotify(): nothing yet.
appearance: none·conic-gradientfrom--pctVisible number in an
aria-hiddensibling.Profile completion
Task completion, so progress.
Said with ariaNotify(): nothing yet.
value="60" max="100"Label says complete what. Each step checked or unchecked says what is left.
Props
| Prop | Does | Default |
|---|---|---|
label | Names the bar. Always visible | Required |
value | How much is done, from 0 to max. Left out, the bar is indeterminate | Absent |
max | How much work in total, in any unit | 100 |
valueText | The value in words when the unit is not percent: “Step 3 of 8”. The same words are visible | — |
shown | The visible copy of the value. null shows none | valueText, or the percent |
look | bar, or ring: the same element, painted | bar |
small · compact | A thinner bar · the label and the bar on one row at any width, for a list of small bars | false |
still | The still stripes of reduced motion on an indeterminate bar, whatever the setting of the person | false |
status · message | working, done, failed or cancelled, and its words, beside the bar | — |
children | The controls: Cancel, Pause, Retry. Plain buttons | — |
Example
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
| Part | Property | Value |
|---|---|---|
| Field | Gap | 8px · 12px (0.5rem · 0.75rem) |
| Label | Text | 13px (0.8125rem) / 1.45, 700 |
| Bar | Height · border · corner | 12px (0.75rem) with its border · 2px · pill. Small: 8px (0.5rem) |
| Fill | Height · corner | The track less its border · pill |
| Fill | Easing | inline-size 300ms ease-out, only where motion is allowed |
| Value text | Text | 12px (0.75rem) / 1.45, monospace, tabular numbers |
| Status | Text · icon | 13px (0.8125rem) / 1.4, 600 · 16px icon, 6px gap |
| Control | Size · corner | 44 × 44px at least · 8px. WCAG 2.5.8 asks 24 × 24px |
| Ring | Size · edges | 64px (4rem) · 2px outside and inside |
| Name · value text · status | Width from 48rem | 8rem · 3.5rem · 11rem |
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}.
| Attribute | Meaning | Default |
|---|---|---|
max | How much work in total. Any unit: bytes, files, steps, 100 | 1 |
value | How much is done, from 0 to max | Absent: indeterminate |
aria-valuetext | The value in words when the unit is not percent: “Step 3 of 8” | None: the number is read |
| Markup | `position` | Reads as |
|---|---|---|
<progress>, or max="100" with no value | -1 | indeterminate |
value="0" | 0 | determinate, empty |
value="40" max="100" | 0.4 | determinate |
value="40", no max | 1 | full bar: clamped to max 1 |
value="150" or "-5", max="100" | 1 · 0 | clamped to max · clamped to 0 |
value="" or "abc" | 0 | 0%, not indeterminate |
max="0", "-1" or "abc" | by value | max falls back to 1 |
States
The element has no error, done or cancelled state, and the fill alone never says what happened: the status line says each, in words and an icon. A red fill is not an error state.
| State | Bar | Status line |
|---|---|---|
| Indeterminate | No value: a purple slice slides over the track | “Uploading report.pdf” |
| Reduced motion | Still stripes keep “unknown” without movement | “Uploading report.pdf” |
| Started, 0% | value="0": determinate and empty | “Uploading report.pdf” |
| Determinate, 40% | value="40": purple fill to 40% | “Uploading report.pdf · 40%”, said at a milestone |
| Done | Full | A check in purple: “Upload complete” |
| Failed | The fill stays where it stopped | A warning in red: “Upload failed. Retry?” |
| Cancelled | The fill stays | A crossed circle: “Upload cancelled” |
Layout
Container queries in rem, so the layout follows 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. The viewport menu of Storybook has 640 CSS px · 200% zoom and 320 CSS px · 400% zoom for any story.
| Breakpoint | CSS width | Reached by | Layout |
|---|---|---|---|
| ≥ 48rem | ≥ 768px | Desktop at 100–150% zoom | One row: name · bar · value · status · control |
| 30–48rem | 480–767px | 1280px at 200% (640 CSS px) · tablets · text at 200% | Name and value on one row, the bar full width, status and control below |
| < 30rem | < 480px | 1280px at 400% (320 CSS px) · phones | Stacked: name, bar, value, status, control. No sideways scroll |
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
appearance: none goes first, or the native look wins and the rules below are ignored. One rule for each engine: a selector list of both pseudo-elements is dropped whole by each, inside :is() and :where() too. The ends take a radius on each fill: overflow: hidden leaves a seam in the end cap.
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;
}
}| Concern | Chromium and Safari | Firefox |
|---|---|---|
| Track | ::-webkit-progress-bar | The element’s own background. No track pseudo-element |
| Border | None by default | Draws its own: set one on purpose (untested) |
| Native height | 16px in Chromium, 21px in WebKit | Not measured |
Modes
| Mode | What happens | Do |
|---|---|---|
| Forced colours | Fill and track both become the page colour and the fill vanishes (Chromium) | Swap to Highlight, Canvas and CanvasText |
| Reduced motion | The sliding slice would loop with no way out | Still stripes: “unknown” stays, movement goes |
| Right-to-left | The native fill grows from the right. A painted ring does not mirror by itself (untested) | Nothing for a bar |
| The fill is a background, dropped unless background graphics are on (Chromium) | print-color-adjust: exact |
Tokens
Component tokens
| Part | Property | Token | Value |
|---|---|---|---|
| Bar | Border width | bw | 2px |
| Bar, ring | Border colour | lilac | #5e548e |
| Bar | Height · corner | — | 12px (8px small) · 999px |
| Track | Fill | — | #ebebec |
| Fill | Fill | lilac | #5e548e |
| Label | Text colour | ink | #16161a |
| Value text | Text colour | ink-soft | #4b4b55 |
| Status, working and cancelled | Text colour | ink | #16161a |
| Status, done | Text and icon | lilac | #5e548e |
| Status, failed | Text and icon | danger | #82002a |
| Status icon, working | Track · arc | — · lilac | #d7d7dc · #5e548e |
| Control | Border · fill · corner | ink · white · radius | #16161a · #ffffff · 8px |
Guidelines
Progress or something else
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.
| Element | Use it for | Finishes | Role |
|---|---|---|---|
progress | Work under way, with or without a known total | Yes | progressbar |
meter | A measurement in a known range | No | meter |
ol + aria-current="step" | One of several named stages | The flow does | list, listitem |
Skeleton in aria-busy | A layout waiting for its content | Yes | none |
| Nothing | A wait of about a second or less | — | — |
Controls by scenario and context
Each row is a use case, drawn with the real component at half size. A control moves under the bar for room; it is never dropped.
- Solid: required in that context, never dropped
- Dashed: optional, or only if there is room
- Status lineOutside the bar: start, done or failed, said once
Zoom 400% · 320 CSS px. At 200% text size the layout drops to the middle column by itself.
One file uploading
Determinate, in percent
- Desktop · 768 px and up48rem · one row
Label · bar · Cancel · status line
Status line
value 68 · max 100, bare percent. Done or failed said once in the status line.
- Smaller viewport · 480–767 px30–48rem
Label · bar · Cancel · status line below
Status line
Cancel moves under the bar; never dropped.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Label · bar · Cancel · status
One per row. Cancel keeps a 44 × 44 target.
Several uploads
One named bar per file
- Desktop · 768 px and up48rem · one row
Per file: label · bar · Cancel
Status line
One progress per file, labelled by its file name. An overall bar needs its own label. Each file that finishes is said once: “b.png uploaded. 2 of 3 files done.”
- Smaller viewport · 480–767 px30–48rem
Per file: label · bar · Cancel (if room). Cancel all
Per-file Cancel moves into the file row menu if there is no room.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Per file: label · bar. Cancel all
File names wrap above each bar.
Importing contacts
Unit is not percent
- Desktop · 768 px and up48rem · one row
Label · bar · “Step 3 of 8” · Cancel
Status line
aria-valuetext “Step 3 of 8”, same words as the visible text. Milestones announced.
- Smaller viewport · 480–767 px30–48rem
Label · bar · Cancel below
Same.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Label · bar · Cancel
“Step 3 of 8” wraps above the bar.
Position in a queue
Spots moved, not a percentage
- Desktop · 768 px and up48rem · one row
Label · bar · “28th · ~4 min” · Leave the queue
aria-valuetext “28th in line, about 4 minutes”. Coarse changes only.
- Smaller viewport · 480–767 px30–48rem
Label · bar · Leave the queue below
Same.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Label · bar · Leave the queue
Position and wait as text above the bar.
Loading the feed
Indeterminate + aria-busy
- Desktop · 768 px and up48rem · one row
Label · bar (no value)
aria-busy
No value attribute. aria-busy on the region until loaded. Shown only after the first second. Said once when it has loaded: “Feed loaded. 3 posts.”
- Smaller viewport · 480–767 px30–48rem
Label · bar
Same.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Label · still bar
Reduced motion: a still bar and the text, no sweep.
Sync of unknown length
Indeterminate + text
- Desktop · 768 px and up48rem · one row
Label · bar · Cancel · status line
Status line
Text says what is happening; no invented percent. Over 10 s: Cancel (2.2.2). Nothing is said while it works; how it ends is said once.
- Smaller viewport · 480–767 px30–48rem
Label · bar · Cancel below
Same.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Label · still bar · Cancel
Same.
Profile completion
Task completion, not running
- Desktop · 768 px and up48rem · one row
Label · bar · 60%
value 60 · max 100. Not a running task: no Cancel. Each step checked or unchecked says what is left: “2 of 5 steps left.” Label says complete what.
- Smaller viewport · 480–767 px30–48rem
Label · bar
Same.
- Zoom 400% · 320 CSS pxUnder 30rem · stacked
Label · bar
Same.
Content
| Part | Format | Example |
|---|---|---|
| Label | What is happening to what. Never “progress bar” | “Uploading report.pdf” · “Importing contacts” |
| Value text | The bare percent, or words when the unit is not percent, the same as in aria-valuetext | “68%” · “Step 3 of 8” · “28th · ~4 min” |
| Control | The action | “Cancel” · “Retry” · “Pause” |
Behavior
| Event | Result |
|---|---|
| The total is unknown | Indeterminate, and text that says what is happening. No invented percent, no bar stuck at 99% |
| The task takes over 10 seconds | A determinate bar and a clearly signposted cancel |
| A control is pressed | It is not disabled: focus stays on it. aria-disabled="true" and the click ignored, or focus moved on purpose |
| Done | “Complete” is said before the bar goes: it stays at 100% or the text replaces it |
| A region is loading | aria-busy="true" on it and aria-describedby at the bar. Removed when done |
Accessibility
Keyboard
| Key | Action | Native |
|---|---|---|
| Tab | Skips the bar: no tabindex. Lands on the control | Yes |
| Enter, Space | On the control: Cancel, Pause or Retry | Yes |
Roles and properties
| Property | Exposed | From |
|---|---|---|
| Role | progressbar | Implicit. No role: no other role is allowed |
| Name | “Uploading report.pdf” | label for, or aria-label or aria-labelledby when there is no room. The text inside the element is a fallback, not a name: it reads empty |
| Value | 68 | value, never aria-valuenow, aria-valuemin or aria-valuemax: aria-valuenow overrides the bar, so it shows 40 and announces 90. aria-valuetext when the unit is not percent |
| Range | 0 to 100 | max |
| Focus | None | tabIndex is -1 |
| Live | None | The bar never announces itself. A tick is never said |
Screen reader
Chromium’s accessibility tree for each markup. No screen reader was run: listen in NVDA, JAWS and VoiceOver before trusting the milestones.
| Markup | Name | Value | Range | Value text |
|---|---|---|---|---|
label for, value="3" max="8" aria-valuetext="Step 3 of 8" | The label | 3 | 0 to 8 | “Step 3 of 8” |
No value, aria-label | The aria-label | None | 0 to 1 | — |
value="40" max="100", fallback text “40%” only | Empty | 40 | 0 to 100 | — |
value="40" max="100" aria-valuenow="90" | — | 90 (!) | 0 to 100 | — |
Announcements
A bar that moves is not a message. The words of the status line are said once when they change, with ariaNotify() from the bar. No live region: where ariaNotify is missing nothing is said. Every 25% is a starting point. Say it from an element that was there before the change and stays: a message on one that is removed, or added in the same update, is lost.
bar.ariaNotify('Upload complete')
bar.ariaNotify('Upload failed. Retry?', { priority: 'high' })| Event | Said | Priority |
|---|---|---|
| It starts | “Uploading report.pdf” | normal |
| Each tick | Nothing | — |
| A milestone, every 25% | “Uploading report.pdf · 50%” | normal |
| Done | “Upload complete” | normal |
| It fails | “Upload failed. Retry?” | high: the next step is the person’s |
| It is cancelled | “Upload cancelled” | normal: the person did it |
| A file of several finishes | “b.png uploaded. 2 of 3 files done.”, from that file’s bar | normal |
| A region with no value has loaded | “Feed loaded. 3 posts.”, from the button that stays: the bar and the list are gone or new | normal |
| A task of unknown length ends | “Sync complete”, and nothing while it works | normal |
| A step of a checklist is checked or unchecked | “2 of 5 steps left.”, from the bar, after it moved | normal: the checkbox says its own state |
Support
| Browser | Fill · track | Checked |
|---|---|---|
| Chromium | ::-webkit-progress-value · ::-webkit-progress-bar | Yes |
| WebKit (Safari) | ::-webkit-progress-value · ::-webkit-progress-bar | Yes |
| Firefox | ::-moz-progress-bar | No |
WCAG criteria
| Criterion | Requirement here |
|---|---|
| 1.3.1 Info and Relationships (A) | label for ties the label to the bar |
| 1.4.1 Use of Color (A) | Done, failed and cancelled are words and an icon, never colour alone |
| 1.4.3 Contrast (Minimum) (AA) | Label 18:1, value text 8.6:1, status words 6.7:1 (done) and 10.6:1 (failed) |
| 1.4.4 Resize Text · 1.4.10 Reflow (AA) | Rem sizes, inline-size: 100%, stacked under 30rem. No sideways scroll at 320 CSS px |
| 1.4.11 Non-text Contrast (AA) | Fill on track 5.62:1, border on page 6.70:1. The track on the page is 1.19:1, which is why the border is there |
| 1.4.12 Text Spacing (AA) | Names and status wrap, never clip |
| 2.2.2 Pause, Stop, Hide (A) | Beside other content and over 5 seconds: a cancel, and the still stripes under reduced motion |
| 2.5.8 Target Size (Minimum) (AA) | The controls are 44 × 44 CSS px at least. 24 × 24 is asked |
| 4.1.2 Name, Role, Value (A) | Name from the label, role from the element, value from value and max |
| 4.1.3 Status Messages (AA) | The start, the milestones, done, failed and cancelled reach assistive technology with ariaNotify(), without moving focus |
Related
This section is still in progress.
References
This section is still in progress.