Shadcn Stepper

Browse 44 shadcn stepper components for multi-step forms, onboarding, billing and shipment tracking. Layouts range from numbered steps to chevron steps, step cards and collapsible sub-steps.

For AI Agents

Hand your agent this brief or the ReUI MCP, not a screenshot. Free to install.

When to use

Forms and setup flows split into numbered steps that people move back and forth through
Shipment, delivery and freight tracking shown as stops with times, ETAs and the leg underway
Incident, ticket, sales, proposal and review workflows laid out as stages, cards, rows or nested tasks

When not to use

A finished screen that runs a billing, invoice or vendor task through numbered steps: use the Wizard blocks
A complete first run account setup shown right after signup, with invites and goals: use the Onboarding blocks
A storefront purchase that takes shipping and card details beside the cart total: use the Checkout blocks

Agent notes

StepperTrigger takes another element through render on the base twin and asChild on the radix twin
Trigger ids come from step alone, so 2 steppers on one page need their own id and aria-controls on each StepperTrigger
StepperContent unmounts every inactive step, so keep field values in parent state or pass forceMount

Third-party API docs

Base UI v1: API reference, docs, llms.txt, through the Base UI twin
Radix UI v1: docs, through the Radix UI twin
Headless Tree v1: API reference, docs, used by 2 of 44 examples
Embla Carousel v8: API reference, docs, used by 1 of 44 examples

Markdownhttps://web.dev.reui.io/components/stepper.md

MCPget_component("stepper")

Installnpx shadcn@latest add @reui/stepper

Full index for agents:llms.txtReUI MCP setup

Shadcn Stepper: Multi-Step Forms, Onboarding and Order Tracking

ReUI Stepper is a custom shadcn component that shows where a person is in a multi-step flow and swaps the content for the step they pick. It is 10 composable parts and 2 hooks, renders as an accessible tab list, and puts every step in 1 of 3 states (active, completed or inactive), with a loading flag for the active step.

The basic examples cover numbered and titled steps, progress and segmented bars, icons and badges, descriptions, a controlled stepper with Previous and Next, and vertical layouts. The newer ones model real flows: shipment tracking, billing setup, new hire onboarding and incident and ticket resolution.

The largest examples nest steps inside steps. 2 more turn the steps into an expandable outline, for purchase order checks and a security review of 29 checks.

What is Shadcn Stepper?

Stepper shows a sequence of steps, marks which one is current, and swaps the content below for the step a person picks. Stepper holds the active step, StepperNav lays the steps out in a row or a column, each StepperItem holds a StepperTrigger (with its indicator, title and description) and a StepperSeparator, and StepperPanel with StepperContent shows the active step's content.

Each step works out its own state: steps before the active one are completed, the active one is active and later ones are inactive. The completed prop marks a later step done for non-linear flows, and the item, trigger, indicator, separator, title and description all carry the state as a data attribute, so a green separator after completed steps is a class, not extra React state.

Why Use Shadcn Stepper?

A multi-step flow needs 3 things a progress bar does not give you: a record of what is done, a way back to an earlier step, and content that changes with the step. Stepper handles all 3, controlled through value and onValueChange or uncontrolled from defaultValue, and leaves the look to you.

For a full screen rather than a component, ReUI Pro builds on the same primitive: all 7 Wizard blocks, 8 of the 9 Onboarding blocks and 5 of the 7 Checkout blocks import Stepper. The wizards alone cover workspace setup, vendor onboarding, team invites, billing upgrades, invoice sending, app publishing and payment flows.

Shadcn Stepper Features

Composable parts. 10 parts and 2 hooks, useStepper and useStepItem, so a step can be a dot, a chevron, a card or a row in a side rail while selection, keyboard handling and ARIA stay in the primitive.
Horizontal and vertical. orientation turns StepperNav into a row or a column. Vertical examples include delivery stops, side rails, status lists and right-aligned sub-steps, and several horizontal ones scroll sideways in a narrow container rather than squeeze their labels.
Indicators for every state. The indicators map sets what a step shows when active, completed, inactive or loading, and falls back to the indicator's children. loading shows only on the active step, so a spinner follows the selection, and the icons come from your own icon set.
Controlled or uncontrolled. Pass value and onValueChange to drive the stepper from your own state, or defaultValue to let it track the step. In controlled mode a click only reports the step, so you decide whether the flow moves.
Route and shipment tracking. Delivery stops with arrival times, a truck route with rest stops, a sea freight route across 5 ports, and checkpoint tracks with timestamps, ETAs and a transit arrow.
Chevron, breadcrumb and segment steps. Interlocking chevron stages for a sales pipeline and for proposal and contract plans, a breadcrumb of step names split by chevrons, and color-coded bars along the top or bottom edge of a panel.
Step cards, side rails and status lists. Clickable step cards in a row or a column, a side rail with an icon per step, and status lists that mark each row with a check, a spinning ring or a vertical bar.
Nested sub-steps. Phases that unfold their tasks in a collapsible card or on an inset rail, with Previous and Next walking all 17 tasks across phases and opening the phase they land in.

ReUI Stepper: In-House Custom Shadcn Component

ReUI Stepper is built and maintained by the ReUI team and is not part of base shadcn/ui. It installs with the shadcn CLI as 1 file in your repository, so you own the source and style it with your Tailwind CSS tokens.

It comes in a Base UI version and a Radix UI version that differ in 1 place: StepperTrigger takes render in the Base UI version and asChild in the Radix version to compose onto another element, such as the Frame panel the step card examples use. Stepper is 1 of 27 ReUI primitives, each documented in both versions with its parts, props and examples.

Use Shadcn Button for Previous and Next below the panel, and Shadcn Badge for a status on a step such as On time or an 8H rest stop. Shadcn Frame and Shadcn Icon Tile give the step cards, side rails and framed headers their surfaces and icons.

For phases with their own tasks, nest a second Stepper inside Shadcn Collapsible so only the open phase shows its sub-steps. When the steps grow into an outline of dozens of checks, Shadcn Tree carries the expand, collapse and keyboard navigation instead.

The assembled versions are ReUI Pro blocks: the 7 Wizard blocks and 8 of the 9 Onboarding blocks run on this primitive. The Stepper docs list every part, prop and hook.

Wizard Blocks in ReUI Pro

The free examples above pair with 7 production ready wizard blocks in ReUI Pro, complete sections built on the same primitives and ready to copy into your app.

Wizard (7 blocks)Multi-step form flows with progress indicators, validation, and step navigation.

Browse all Application blocks

Frequently Asked Questions

How is Stepper different from Timeline?

Stepper is interactive: its steps are tabs a person clicks or reaches with the keyboard, and the content below changes with the selected step. Timeline is a read-only list of events that marks entries up to its value as completed, with no triggers, keyboard handling or content panels. Use Stepper for a flow someone moves through, and Timeline for a history they read.

How do I stop people moving on until a step is valid?

Run the stepper controlled with value and onValueChange. A click on a step only calls onValueChange with that step, so validate the current step first and ignore the call when it fails, and disable the Next button the same way. Mark steps that cannot be reached yet with disabled on their StepperItem.

Do earlier steps keep what was typed when I go back?

Not by default. StepperContent renders only the active step, so the fields of other steps unmount and uncontrolled inputs lose their values. Keep the values in parent state or a form library, or pass forceMount so every panel stays in the page, hidden while inactive.

Can an earlier step show as skipped or incomplete?

Not through the step state. Every step before the active one is completed whatever happened in it, and the completed prop can mark a step done but never undo one. Keep skipped steps in your own state and style that StepperItem with a class, and leave the completed entry out of the indicators map, because it wins over the indicator's children.

Is Stepper keyboard accessible?

Yes. It renders a tab list with a tab per step, aria-selected on the current one and roving focus, so Tab lands on the selected step. Arrow keys move focus between steps and wrap at the ends, Home and End jump to the first and last, and Enter or Space selects. The newer examples also move focus to the other button when Previous or Next turns disabled at either end.

Can I put 2 steppers on one page, or nest one inside another?

Yes. Give each StepperTrigger its own id and aria-controls, for example from useId, so the ids stay unique on the page. The vertical step card, status list and nested sub-step examples show the component.

What's the difference between Radix and Base UI versions of ReUI Stepper?

Only StepperTrigger differs. The Base UI version takes render and the Radix version takes asChild to place the trigger on another element, and the state logic, keyboard handling, markup and classes are the same. Choose the version that matches the rest of your shadcn primitives.

Start building with ReUI Pro today.

Every Pro block, every style, and every future addition, with one license for unlimited projects.

Get All-Access

From $249, once. Lifetime updates.