Stepper
Show where a person is in a multi-step flow and what is done.
pnpm dlx shadcn@latest add @uiarc/stepperLive · keyboard ready
Set up your workspace
- Showing position in a strict multi-step flow like checkout or account setup.
- Flows where people can jump back to completed steps, via onStepSelect.
- Vertical timelines of steps with descriptions and error states.
- Use multi-step-form when you also want the step content, navigation, and success state.
- Use onboarding-checklist for loosely ordered tasks.
- Use progress when a single percentage is enough.
Installation
Add Stepper with the shadcn CLI, or copy the source by hand.
pnpm dlx shadcn@latest add @uiarc/stepperAdds the component and its local dependencies, and installs motion. First time? Add the @uiarc registry to components.json, or use the full URL:
example.tsx
import { Stepper } from "@/registry/components/stepper/stepper"; export function CheckoutSteps({ step, goTo }: { step: number; goTo: (index: number) => void }) { return ( <Stepper current={step} onStepSelect={goTo} steps={[ { id: "cart", label: "Cart" }, { id: "shipping", label: "Shipping", description: "Address and delivery" }, { id: "payment", label: "Payment" }, ]} /> );}Stepper
A horizontal or vertical steps indicator driven by the current index, with optional navigation back to completed steps.
PropTypeDefaultDescription
stepsRequired{ id: string; label: string; description?: string; error?: string }[]–Steps in order. error morphs the marker into an alert and replaces the description.currentRequirednumber–Index of the step in progress. steps.length marks the flow complete.orientation"horizontal" | "vertical""horizontal"Layout direction.onStepSelect(index: number) => void–Called with the index of a completed step when chosen. Without it the stepper is read only.details"all" | "current""all""current" shows only the active step's description. Errors always show.compactbooleanfalseMarkers only. Horizontal steppers switch to this below 30rem on their own.labelstring"Progress"Accessible name for the stepper.completeLabelstring"All steps complete"Announced, and shown in the compact caption, once every step is complete.classNamestring–Class on the root.- ArrowLeftorArrowRightorArrowUporArrowDown
- With onStepSelect, moves focus between reachable steps (RTL aware).
- HomeorEnd
- Jumps to the first or the current step.
- EnterorSpace
- Selects a completed step.
- Renders a labelled nav when interactive, otherwise role="group"; the current step has aria-current="step".
- Each step appends screen-reader-only status text: Completed, Not started, or Error.
- Step changes are announced in a polite live region as "Step 2 of 4: Shipping".
- Upcoming steps are aria-disabled and removed from the tab order.
- Connectors fill one after another when progress jumps several steps; the ring then grows around the new current marker.
- Numbers morph into drawn checks or alerts; descriptions rise in while their slot springs to the new height.
- Reduced motion applies all changes instantly.
- Horizontal steppers switch to markers only with a caption below a 30rem container width.
- Set orientation to vertical for sidebars or narrow columns where labels and descriptions should stay visible.
- Labels and descriptions wrap with overflow-wrap, so long words do not overflow.
- The stepper only indicates; it renders markers and text, with a ResizeObserver for the description slot height.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
- Use to show position in a strict multi-step flow such as checkout or setup. Use onboarding-checklist for loosely ordered tasks.
- The stepper only indicates; render the step content yourself and drive current. Set current to steps.length when done.
The full library index for assistants is at /llms.txt.