Design System

Design System

Progress

Indicators

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

On this page

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

  1. Label

    label for

    Names the bar. Always visible. “Progress bar” is not part of the name.

  2. Value text

    span aria-hidden="true"

    The visible copy of the value. Hidden because the bar already exposes it.

  3. Track

    progress, ::-webkit-progress-bar

    The whole scale, 0 to max. The element holds the role, the name, the value and the range.

  4. Fill

    ::-webkit-progress-value, ::-moz-progress-bar

    The part done. With no value it is absent and a slice slides over the track.

  5. Status

    p with an svg

    What the task is doing, in words and a shape. A change of its words is said once.

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

    68%

    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 progress per file, the label is the file name

    An overall bar needs its own label. Each file that finishes is said once.

  • Importing contacts

    Unit is not percent.

    Step 3 of 8

    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.

    28th · ~4 min

    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-busy on the region

    Remove aria-busy when done, and say it has loaded.

  • Sync of unknown length

    Indeterminate + text.

    Said with ariaNotify(): nothing yet.

    No value · text says what is happening

    No invented percentages. Said when it ends.

  • Percent ring

    Same native element, painted.

    45%

    Said with ariaNotify(): nothing yet.

    appearance: none · conic-gradient from --pct

    Visible number in an aria-hidden sibling.

  • Profile completion

    Task completion, so progress.

    60%
    Finish your profile

    Said with ariaNotify(): nothing yet.

    value="60" max="100"

    Label says complete what. Each step checked or unchecked says what is left.

Props

Props
PropDoesDefault
labelNames the bar. Always visibleRequired
valueHow much is done, from 0 to max. Left out, the bar is indeterminateAbsent
maxHow much work in total, in any unit100
valueTextThe value in words when the unit is not percent: “Step 3 of 8”. The same words are visible—
shownThe visible copy of the value. null shows nonevalueText, or the percent
lookbar, or ring: the same element, paintedbar
small · compactA thinner bar · the label and the bar on one row at any width, for a list of small barsfalse
stillThe still stripes of reduced motion on an indeterminate bar, whatever the setting of the personfalse
status · messageworking, done, failed or cancelled, and its words, beside the bar—
childrenThe 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

Measurements
PartPropertyValue
FieldGap8px · 12px (0.5rem · 0.75rem)
LabelText13px (0.8125rem) / 1.45, 700
BarHeight · border · corner12px (0.75rem) with its border · 2px · pill. Small: 8px (0.5rem)
FillHeight · cornerThe track less its border · pill
FillEasinginline-size 300ms ease-out, only where motion is allowed
Value textText12px (0.75rem) / 1.45, monospace, tabular numbers
StatusText · icon13px (0.8125rem) / 1.4, 600 · 16px icon, 6px gap
ControlSize · corner44 × 44px at least · 8px. WCAG 2.5.8 asks 24 × 24px
RingSize · edges64px (4rem) · 2px outside and inside
Name · value text · statusWidth from 48rem8rem · 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}.

Attributes
AttributeMeaningDefault
maxHow much work in total. Any unit: bytes, files, steps, 1001
valueHow much is done, from 0 to maxAbsent: indeterminate
aria-valuetextThe value in words when the unit is not percent: “Step 3 of 8”None: the number is read
Position by markup
Markup`position`Reads as
<progress>, or max="100" with no value-1indeterminate
value="0"0determinate, empty
value="40" max="100"0.4determinate
value="40", no max1full bar: clamped to max 1
value="150" or "-5", max="100"1 · 0clamped to max · clamped to 0
value="" or "abc"00%, not indeterminate
max="0", "-1" or "abc"by valuemax 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.

States
StateBarStatus line
IndeterminateNo value: a purple slice slides over the track“Uploading report.pdf”
Reduced motionStill 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
DoneFullA check in purple: “Upload complete”
FailedThe fill stays where it stoppedA warning in red: “Upload failed. Retry?”
CancelledThe fill staysA 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.

Layout
BreakpointCSS widthReached byLayout
≥ 48rem≥ 768pxDesktop at 100–150% zoomOne row: name · bar · value · status · control
30–48rem480–767px1280px at 200% (640 CSS px) · tablets · text at 200%Name and value on one row, the bar full width, status and control below
< 30rem< 480px1280px at 400% (320 CSS px) · phonesStacked: 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;
  }
}
Engines
ConcernChromium and SafariFirefox
Track::-webkit-progress-barThe element’s own background. No track pseudo-element
BorderNone by defaultDraws its own: set one on purpose (untested)
Native height16px in Chromium, 21px in WebKitNot measured

Modes

Modes
ModeWhat happensDo
Forced coloursFill and track both become the page colour and the fill vanishes (Chromium)Swap to Highlight, Canvas and CanvasText
Reduced motionThe sliding slice would loop with no way outStill stripes: “unknown” stays, movement goes
Right-to-leftThe native fill grows from the right. A painted ring does not mirror by itself (untested)Nothing for a bar
PrintThe fill is a background, dropped unless background graphics are on (Chromium)print-color-adjust: exact

Tokens

Component tokens

Component tokens
PartPropertyTokenValue
BarBorder widthbw2px
Bar, ringBorder colourlilac#5e548e
BarHeight · corner—12px (8px small) · 999px
TrackFill—#ebebec
FillFilllilac#5e548e
LabelText colourink#16161a
Value textText colourink-soft#4b4b55
Status, working and cancelledText colourink#16161a
Status, doneText and iconlilac#5e548e
Status, failedText and icondanger#82002a
Status icon, workingTrack · arc— · lilac#d7d7dc · #5e548e
ControlBorder · fill · cornerink · 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.

Alternatives
ElementUse it forFinishesRole
progressWork under way, with or without a known totalYesprogressbar
meterA measurement in a known rangeNometer
ol + aria-current="step"One of several named stagesThe flow doeslist, listitem
Skeleton in aria-busyA layout waiting for its contentYesnone
NothingA 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

    Live example

    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

    Live example

    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

    Live example

    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

    Live example

    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

    Live example

    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

    Live example

    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

    Live example

    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

Content
PartFormatExample
LabelWhat is happening to what. Never “progress bar”“Uploading report.pdf” · “Importing contacts”
Value textThe bare percent, or words when the unit is not percent, the same as in aria-valuetext“68%” · “Step 3 of 8” · “28th · ~4 min”
ControlThe action“Cancel” · “Retry” · “Pause”

Behavior

Behavior
EventResult
The total is unknownIndeterminate, and text that says what is happening. No invented percent, no bar stuck at 99%
The task takes over 10 secondsA determinate bar and a clearly signposted cancel
A control is pressedIt 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 loadingaria-busy="true" on it and aria-describedby at the bar. Removed when done

Accessibility

Keyboard

Keyboard
KeyActionNative
TabSkips the bar: no tabindex. Lands on the controlYes
Enter, SpaceOn the control: Cancel, Pause or RetryYes

Roles and properties

Roles and properties
PropertyExposedFrom
RoleprogressbarImplicit. 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
Value68value, 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
Range0 to 100max
FocusNonetabIndex is -1
LiveNoneThe 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.

Screen reader
MarkupNameValueRangeValue text
label for, value="3" max="8" aria-valuetext="Step 3 of 8"The label30 to 8“Step 3 of 8”
No value, aria-labelThe aria-labelNone0 to 1—
value="40" max="100", fallback text “40%” onlyEmpty400 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' })
Announcements
EventSaidPriority
It starts“Uploading report.pdf”normal
Each tickNothing—
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 barnormal
A region with no value has loaded“Feed loaded. 3 posts.”, from the button that stays: the bar and the list are gone or newnormal
A task of unknown length ends“Sync complete”, and nothing while it worksnormal
A step of a checklist is checked or unchecked“2 of 5 steps left.”, from the bar, after it movednormal: the checkbox says its own state

Support

Support
BrowserFill · trackChecked
Chromium::-webkit-progress-value · ::-webkit-progress-barYes
WebKit (Safari)::-webkit-progress-value · ::-webkit-progress-barYes
Firefox::-moz-progress-barNo

WCAG criteria

WCAG criteria
CriterionRequirement 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.