Usage
current step id; optional error, optional, and disabledReason fields on a step adjust copy and markers without replacing progress (see Accessibility for how assistive technology reads errors). The vertical rail is a summary: one-sentence descriptions per step, not badges or counts.
| Prop | Role |
|---|---|
steps | Flat list data: id, label, optional description, error, optional, disabledReason. Mutually exclusive with sections. |
sections | Horizontal-only grouped steps: { id, label, steps }[]. Mutually exclusive with steps. |
sectionSummary | Horizontal sectioned layout only: ( { index, count } ) => LocalizedMessage for the current section (for example "Step 2 of 4"). Renders nothing when omitted. |
current | Controlled id of the active step. Unknown ids warn once and leave no step current. |
stateLabels | Required hidden text for every StepperState, including Error. |
announcement | Optional (change) => LocalizedMessage for one polite sentence when a step becomes current or complete after mount. |
onStepSelect | When set, eligible steps render as buttons; arrow keys rove among them. |
selection | StepperSelection.Completed (default) or All to widen which steps are buttons. |
orientation | Horizontal (default) or Vertical. |
compact | Horizontal only: hides non-current labels visually while keeping them in the accessible name. |
current drives complete, current, and upcoming. When step.error is set, the row still uses its progress position and title. The marker shows an alert glyph, visible error copy replaces the description, and assistive technology hears the progress state label, then the error state label, then the label and error message. Only rows with error add the extra hidden error state text.
optional appends muted suffix copy after the label (read after the title). disabledReason dims the title, replaces the description, and prevents selection. These flags are built for wizard flows; there is no recorded UX Core ruling that optional steps are approved for merge—ship the API additively and avoid claiming approval in copy.
Connector fills animate forward with token spring motion and stagger up to four segments; backward jumps snap instantly. Marker check swaps use glide enter and exit tokens. Under prefers-reduced-motion: reduce or data-motion="reduced" on the document root, transform transitions and stagger delays are zeroed while layout and state stay the same.
Put a long step list in a bounded Scrollable; the rail beside a scrolling form stays fixed while fields scroll (see Composition stories). Labels wrap; the marker aligns to the first line.
For horizontal layout, the stepper establishes its own inline-size container. Below the centered-block breakpoint (640px in breakpoints.json), markers stay on the track, per-step labels and descriptions hide visually (they remain in the accessible name), and the current step label (plus the current section label when sections is set) appears in a fold footer. Nothing in the assignment requires the caller to wrap the stepper for the fold.
Pass sections instead of steps when a long wizard needs grouped steps on one track (for example more than seven steps in a pinned top stepper). Each section is one track node with a marker, connector, and section label below; the current section may also show sectionSummary and the current step title. Section progress is complete when every step in the section is complete, current when it holds current, error when any step has error and the section is not complete, otherwise upcoming. Vertical layout does not take sections; the FormWizard rail renders section headings separately.