Navigation
Stepper
Shows progress through a multi-step flow — onboarding, checkout, a setup wizard. Each step reports its status at a glance: done, current, still to come, or needs attention.
npx shadcn@latest add @orbit/stepperOverview
A live wizard: the stepper drives the panel below it. Step through with Back and Continue, or click a completed indicator to jump back.
- AccountYour details
- WorkspaceName & members
- First projectPick a template
- ReviewConfirm & finish
A workspace is where your team’s projects live. Give it a name and invite a few people to start.
Anatomy
Three pieces repeat per step: the indicator — a numbered 30px circle that becomes a check when done, a ring when current, or a cross on error; the 2px connector, which fills with the accent up to the furthest completed step; and the label — a 13.5px title with an optional 12px description beneath, muted until the step is reached.
- IndicatorCheck, ring, or cross
- ConnectorFills with the accent
- LabelTitle + description
Statuses
Completed steps show a check, the current step is ringed and highlighted, upcoming steps are muted, and an error step turns red to flag a problem to fix before moving on.
- AccountYour details
- WorkspaceName & members
- First projectPick a template
- ReviewConfirm & finish
- AccountYour details
- WorkspaceName & members
- First projectNeeds attention
- ReviewConfirm & finish
- AccountYour details
- WorkspaceName & members
- First projectPick a template
- ReviewConfirm & finish
Orientation
Stacked vertically, the current step can reveal its content inline — handy for a side rail or a settings wizard where each step expands in place.
- AccountYour details
- WorkspaceName & members
- First projectPick a templateStart from a template or a blank board — you can change it later.
- ReviewConfirm & finish
- Account
- WorkspaceCreate a workspace and invite the people you’ll collaborate with.
- First project
- Review
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| steps | StepperStep[] | — | Steps in order — { title, description?, content? }. content renders inline under the current step in vertical orientation. |
| activeStep | number | 0 | Controlled index of the current step. Pass steps.length to mark the whole flow complete. |
| orientation | "horizontal" | "vertical" | "horizontal" | Connectors run along the chosen axis; vertical steppers can expand content in place. |
| descriptions | boolean | true | Show the one-line description under each title. |
| errorStep | number | null | null | Index of a step that needs attention — danger ring, cross glyph, and a “Needs attention” description. |
| onStepClick | (index: number) => void | — | Makes completed steps clickable so users can jump back. Current and upcoming steps stay inert. |
| …rest | OlHTMLAttributes | — | Everything else is forwarded to the root <ol>, including ref. |
Usage
A stepper sets expectations — it should tell the user how far they’ve come and how much is left.
Keep steps to a handful
Three to five named steps is the sweet spot; more than that and people lose the thread.
Let labels wrap
Step titles should be one or two words — push detail into the description or the panel.
Flag errors on the step
If a step has an invalid field, mark it red so the user knows exactly where to go back.
Allow skipping ahead silently
Only let users jump to a step they’ve reached, or gate forward steps until the current one is valid.
Keyboard & accessibility
Steps render as an ordered list; the current indicator carries aria-current="step", unreachable indicators are aria-disabled and out of the tab order, and done / error states are conveyed by glyphs and screen-reader text — never color alone. Clickable completed steps are real buttons with the themed 3px focus ring.