Skip to content

Progress

C-21 · Components · Feedback

All elements · Progress on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Progress.

Progress

C-21WCAG 2.2 AA · Passed #414
Axis Values
data-variant linear (default) · circular
data-indeterminate · data-size · data-color flag / sm · md · lg / primary · success · warning · error · info
style="--_value: 42" determinate value 0–100
Linear
Uploading 3 of 5 files0%
Circular
65%
100%

Guidance

When to use

  • Show how far an upload, export or batch job has gone when the total is known, with --_value from 0 to 100.
  • Show that work is under way when the total is unknown with data-indeterminate.
  • Show a measure against a limit, such as storage used, with data-color set to warning as it nears the limit.
  • Use the circular variant inside a button, row or tile where a bar does not fit, with the percentage in the middle at larger sizes.

When to consider something else

  • When the layout of the content is known and only the data is loading, use Skeleton. See Skeleton.
  • When a whole region is loading and empty, use Empty state's loading variant. See EmptyState.
  • When the user sets a value rather than watching one, use Slider. See Slider.
  • When the progress is through named steps, use Step indicator. See StepIndicator.

Usability

Do
  • Pair a bar with a visible label and value, such as "Uploading 3 of 5 files" and the percentage, using .qf-progress-label.
  • Switch from indeterminate to determinate as soon as the total is known.
  • Use the error color with a message when a job fails, and say what to do next.
  • Offer Cancel next to long-running jobs.
Don’t
  • Don't show progress for work that takes under about a second.
  • Don't let a determinate bar move backward.
  • Don't use color alone to say the job failed or finished.

Accessibility

Keyboard

No keyboard interaction of its own.

Roles and names

  • Each bar has role="progressbar" and a name from aria-labelledby (pointing at the visible label) or aria-label.
  • Determinate bars carry aria-valuenow, with aria-valuemin="0" and aria-valuemax="100"; the binding must keep aria-valuenow in step with --_value.
  • Indeterminate bars omit aria-valuenow.
  • Add aria-valuetext when the percentage is less useful than words, such as "3 of 5 files".
  • The region the bar describes should carry aria-busy="true" while it loads.

Focus

  • Progress is not focusable and must not take focus.
  • When the job finishes, do not move focus; announce the result instead.

Other requirements

  • Progress has no keyboard behavior; it only reports state.
  • Screen readers do not reliably announce value changes; announce start, key milestones and completion through a polite live region or Toast (4.1.3), not every percent.
  • The indeterminate and fill animations stop under prefers-reduced-motion (2.3.3); the label text must still say work is under way.
  • The fill needs 3:1 against the track, including the light track in both themes (1.4.11).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Progress test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order.
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- progress --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Progress package
Source css/classic/components/content.css
Specimens also use Box · Card · Chip · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes