Stepper
Progress through a multi-step flow; the steps a user may revisit depend on your validation.
Installation
Run it from the root of a project already set up with zunoui init.
npx zunoui@latest add stepperDependencies
What add stepper installs alongside the component. The CLI skips any you already have in a compatible version.
ZUNO registry
@zuno/utils
Examples
2 examples · 1 componentA checkout flow
Continue moves forward; completed steps can be revisited.
Vertical with an error
A step that failed validation is marked in color and in words.
API reference
Configured through props: pass the steps and the current one; which steps can be visited is decided by your validation.
| Prop | Type | Default |
|---|---|---|
stepsThe stages in order. error marks one that needs attention, in its color and in words. | { id; label; description?; error? }[] | — |
currentThe id of the step being shown. | string | — |
onStepChangeCalled when a visitable step is chosen. Without it, every step is text. | (id: string) => void | — |
canVisitWhich steps are buttons. Use it to allow jumping ahead once your validation passes. | (step, index) => boolean | completed steps |
orientationHorizontal wraps on narrow screens; vertical suits a sidebar. | "horizontal" | "vertical" | "horizontal" |
stepLabel / labelsVisible step numbers and the hidden state words, for translation. | (position) => ReactNode / { completed; error } | "Step 1" / "Completed", "Needs attention" |
States
The states that apply to this component and their visual treatment.
| State | Treatment |
|---|---|
| Complete | A primary bar; a button when visitable. |
| Current | A primary bar and aria-current="step". |
| Upcoming | A neutral bar and dimmed text. |
| Error | A red bar and "Needs attention" for screen readers. |
Accessibility
A nav landmark ("Progress") with an ordered list, so the number of steps and each position are announced.
The current step carries aria-current="step". Completed and erroneous steps start with hidden text ("Completed:", "Needs attention:"), so the state is not conveyed by color alone.
Only visitable steps are buttons; the current and upcoming ones are text, so Tab only lands on steps that can be opened.
Moving between steps changes the form below: move focus to its heading after onStepChange so keyboard users land on the new content.
Validation stays in your form; the stepper only reflects it through canVisit and error.