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 | Data for each row: id, label, optional description, error, optional, disabledReason. |
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.
Per-step badges or counts in the rail, footer Back/Next, or horizontal descriptions below 640px in form wizards (handled in later form-wizard work).