Skip to content

StepIndicator

C-47 · Components · Navigation

All elements · StepIndicator on the Components page

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

Copies the bun run a11y:approve command for StepIndicator.

StepIndicator

C-47WCAG 2.2 AA · Passed

Where the user is in a fixed, ordered process, such as a multi-page application form: one segment per step, and a "Step 2 of 5" heading naming the current one. Modeled on the USWDS Step indicator. It shows status only; the pages themselves move the user on. It is the system's one stepper: the Tabs stepper variant (.qf-stepper) folded into it.

Axis Values
data-variant segments (default) · counters (a numbered circle on each segment)
data-size counters only: md 2rem (default) · sm 1.5rem
data-labels visible (default) · hidden (the heading names the step); below 30rem of width the labels hide on their own
__segment[data-state="complete"] · __segment[aria-current="step"] · __segment complete · current · upcoming; each label ends in a visually hidden "completed" or "not completed" (none on the current step)
__heading › __counter (__current · __total) · __heading-text the "Step N of M" heading, at the level the page needs
Segments with labels
  1. Personal information completed
  2. Household status completed
  3. Supporting documents
  4. Signature not completed
  5. Review and submit not completed

Step3of 5Supporting documents

Counters · small counters
  1. Upload completed
  2. Classify completed
  3. Index
  4. Review not completed
  5. Done not completed

Step3of 5Index

  1. Request completed
  2. Approval
  3. Fulfilment not completed
Labels hidden · first step · last step
  1. Personal information
  2. Household status not completed
  3. Supporting documents not completed
  4. Signature not completed
  5. Review and submit not completed

Step1of 5Personal information

  1. Upload completed
  2. Classify completed
  3. Index completed
  4. Review

Step4of 4Review

Narrow (under 30rem the labels hide; the heading still names the step)
  1. Personal information completed
  2. Household status
  3. Supporting documents not completed
  4. Signature not completed
  5. Review and submit not completed

Step2of 5Household status

Guidance

When to use

  • Show where the user is in a fixed, ordered process of three to seven steps, such as a multi-page application, a filing or an indexing workflow.
  • Put it at the top of every page of the process, above the page's form, so the user always sees how far they are and how much is left.
  • Use the counters variant when the step number matters to the user, for example when instructions or a help line refer to "step 3".
  • Hide the labels (data-labels="hidden") when the step names are long or many; the heading still names the current step.

When to consider something else

  • When the views are peers the user may visit in any order, use Tabs; a step indicator implies an order. See Tabs.
  • When the progress is a measured amount, such as an upload or an import, use Progress. See Progress.
  • When the user is paging through data rather than moving through a process, use Pagination. See Pagination.
  • When the steps are pages of one form, put the step indicator above the Form composite on each page. See Form.
  • When the process has one or two steps, leave the indicator out; a page heading is enough.

Usability

Do
  • Keep step labels short (one to three words) and use the same words as each page's heading.
  • Keep the number of steps fixed for the whole process; if a step can be skipped, keep its segment and mark it complete.
  • Repeat the current step's name in the heading ("Step 3 of 5 Supporting documents") so the step is clear without the labels.
  • Let users go back to a completed step with the page's own Back button or a summary page, not by clicking segments.
  • Mark a step complete only when its page is valid and saved.
Don’t
  • Don't make segments links or buttons; the indicator is a status display, and clickable segments invite skipping required steps.
  • Don't use more than seven steps; split a long process into parts with their own indicator.
  • Don't rely on the segment colors alone; keep the visually hidden "completed" and "not completed" text and the heading.
  • Don't put two step indicators on one page.

Accessibility

Keyboard

No keyboard interaction of its own.

Roles and names

  • The segments are an ordered list (ol) with an aria-label naming the process, such as "Application progress", so screen readers announce the number of steps.
  • The current segment carries aria-current="step"; the others carry no ARIA state.
  • Each label ends in a visually hidden "completed" or "not completed" (.qf-sr-only); the current step has neither, since aria-current already says so.
  • The header is a real heading (h2–h4, at the level the page needs) holding a visually hidden "Step", the current number, "of M" and the step name.
  • Counter numbers are CSS-generated and are not read; the heading carries the number.

Focus

  • Nothing in the indicator takes focus.
  • When a new step's page loads, move focus to the page heading or the step indicator's heading so screen reader users hear where they are.

Other requirements

  • Segment fills are graphical objects that meet 3:1 against the page in both themes (1.4.11): complete is primary-800, current primary-main (blue-300 in dark), upcoming slate-400 (slate-500 in dark).
  • Complete and current differ by more than color: the current label is bold and the heading names it (1.4.1).
  • Below 30rem of width the labels hide on their own and the heading carries the step name, so the indicator reflows at 320px (1.4.10).
  • In forced-colors mode the fills become system colors so complete and current still differ from upcoming.

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.

StepIndicator 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 -- step-indicator --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.

StepIndicator package
Source css/classic/components/step-indicator.css
Specimens also use Box · Card · Chip · Table · Text · Toolbar
Sprites —
React Not yet available: the React binding has not started.

Latest updates

StepIndicator latest updates
Date Version Breaking Description
2026-10-20 0.1 No StepIndicator (C-47), modeled on the USWDS Step indicator: an ordered list of segments (.qf-step-indicator__segment), each complete (data-state="complete"), current (aria-current="step") or upcoming, with a visually hidden "completed" / "not completed" in each label, under a "Step N of M" heading that names the current step. data-variant="counters" puts a numbered circle on each segment (data-size="sm" for the small one); data-labels="hidden" leaves the heading to name the step, and below 30rem of width the labels hide on their own (components/step-indicator.css, tokens-components.css)

All release notes