Stepperize v9Explore the changes
Skip to Content
Stepperize

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.

The pattern follows the flow

There is no single correct markup for a stepper, so the primitives pick it from how the flow behaves.

FlowMarkup
linearAn ordered list of steps. The triggers are plain buttons; the current one has aria-current="step", and steps that are not reachable yet are disabled. Each panel is a group named after the step's title.
Free navigation, with triggersTabs: tablist, tab and tabpanel, linked with aria-controls and aria-labelledby.
No triggersNo tabs either: each panel is a group named after the step's title.

A linear flow is not a set of tabs: its steps cannot be opened in any order, and announcing them as tabs would promise that they can.

What is handled

BehaviorDetail
KeyboardIn tabs, arrow keys, Home and End move between steps, and the selected tab is the list's single tab stop. Left and right swap in right-to-left layouts. In a linear flow the triggers are ordinary buttons in the tab order.
FocusIf focus would be lost after a step change (a field in a panel that unmounted, a button that became disabled), it moves to the new panel. Focus outside the stepper is never moved.
AnnouncementsWhen the step changes while focus stays put, for example on Next, a polite live region announces the new step's title.
Async checksWhile a schema, guard or onFinish runs, the buttons keep focus: they are aria-disabled rather than disabled, and the root has aria-busy.
Valid markupTitle and Description are spans, so they are valid inside the trigger's button.

What only you can provide

  • A name for every trigger. Stepper.Indicator is hidden from screen readers. If a trigger only shows a number or an icon, name it:

    <Stepper.Trigger aria-label={step.title}>
      <Stepper.Indicator />
    </Stepper.Trigger>
  • A name for the stepper. The root is labelled "Stepper". Pass aria-label or aria-labelledby to describe the flow, and to translate it.

  • Completion beyond color. data-state is for styling. Add text for screen readers, in your language:

    function Label() {
      const item = Stepper.useItem();
      return (
        <>
          <Stepper.Title />
          {item.state === "complete" && <span className="sr-only">Completed</span>}
        </>
      );
    }
  • A string title on every step. Announcements and the names of panels without triggers come from it.

  • Error messages next to their fields. issues() gives you the messages; connect them to the inputs with aria-describedby and aria-invalid.

Development checks

In development, mistakes that can be detected are reported with a code: a render function that drops its props, a trigger without an accessible name, a trigger outside its list. See Errors and warnings.

Edit on GitHub

Last updated on

On this page