Accessibility
What the primitives handle for you, and the few things only you can provide.
The primitives are accessible without configuration. This page lists what they do, so you know what is covered, and what is left to you.
What the primitives do
| Behavior | Detail |
|---|---|
| Roles and relationships | Stepper.List is a tablist, each Trigger a tab linked to its Content (tabpanel) through aria-controls and aria-labelledby. Items are presentational inside the list. |
| Keyboard | Arrow keys, Home and End move between steps. Left and right swap in right-to-left layouts. The selected step is the list's single tab stop. |
| Unreachable steps | Steps the navigation policy blocks (for example with linear) are disabled. Screen readers still list them as unavailable. |
| Focus | If focus would be lost after a step change (a field in the panel that unmounted, Next disabled or replaced on the last step), it moves to the new panel. Focus outside the stepper is never touched. |
| Announcements | When the step changes while focus stays put (for example on Next), a polite live region announces the new step's title. It stays quiet when a focused tab or panel already reads the step. |
| Async guards | While beforeStepChange runs, triggers, Prev and Next keep focus: they get aria-disabled instead of disabled, and the Root sets aria-busy. A rejected change leaves focus where it was. |
| Valid markup | Inside a Trigger (a button), Title and Description render a span. Elsewhere they render h4 and p. |
| Flows without triggers | With only Content and Next, or a list of indicators, there are no tabs: the list is a plain list and each panel a group named after the step's title. |
Styling disabled and pending states
disabled: variants keep working for blocked steps and for Prev / Next at
the edges. data-disabled is also set, and additionally covers the moment a
guard is running, when buttons are aria-disabled rather than disabled:
<Stepper.Next className="data-disabled:opacity-50 data-pending:cursor-progress" />What only you can provide
-
A name for every trigger.
Stepper.Indicatoris hidden from screen readers. If a trigger only shows a number or an icon, passaria-label:<Stepper.Trigger aria-label={step.title}> <Stepper.Indicator /> </Stepper.Trigger> -
A name for the stepper. The Root is labelled "Stepper". Pass
aria-labeloraria-labelledbyto describe the flow, and to translate it. -
Completion beyond color.
data-completeis for styling. Add text for screen readers, in your language, withStepper.useItem():function Label() { const item = Stepper.useItem(); return ( <> <Stepper.Title /> {item.complete && <span className="sr-only">Completed</span>} </> ); } -
A string
titleon every step. Announcements and the names of panels without triggers come from it. Steps without a stringtitleare not announced.
Development checks
In development, Stepperize warns about mistakes it can detect, with a code and
a link: a render function that drops its props, a trigger without an
accessible name, or a trigger outside its list. See
Errors and warnings.
Last updated on