Shadcn Stepper Components

Shadcn Stepper Component

The Shadcn Stepper is a React component for multi step flows such as checkouts, onboarding and setup wizards. It shows where the user is, which steps are done and what comes next, and it renders the content of the active step for you.

These shadcn stepper variants cover numbered and icon indicators, loading states, titles and descriptions, progress bar steps, a segmented questionnaire, vertical timelines and a complete multi step form inside a card. Everything is built with shadcn/ui, React and Tailwind CSS, and the trigger uses the render utility from Base UI.

What is the Shadcn Stepper Component?

A stepper splits a long task into ordered steps. Stepper holds the active step, StepperNav lists the steps, and StepperPanel shows the StepperContent that matches the active value. Each StepperItem is completed, active or inactive based on its position, and exposes that state as a data-state attribute for styling.

Use a stepper when the order of the steps matters. For switching between equal views use Tabs, for a single completion value use Progress, and for moving through pages of results use Pagination.

Anatomy of the Shadcn Stepper

14 Shadcn Stepper Variants

Each stepper variant listed here is previewed live at the top of this page, together with its source code and install command.

• Basic: Four numbered steps joined by separators, with the content of the active step below.
• Loading indicators: Small outlined indicators with a dot for the active step, a check for completed steps and a spinner while the step is loading.
• Controlled: The active step lives in React state and Previous and Next buttons move through the flow.
• Title: Titles centered under each indicator with the separator running between the circles.
• Title without separators: Left aligned indicators and titles laid out as equal columns, without connector lines.
• Icons and status badges: Icon indicators with a step label, title and an In progress, Completed or Pending badge.
• Title and description: A title and a short description under each indicator; the description hides on small screens.
• Inline title: Indicator and title on one line, like a checkout header.
• Inline title and description: Indicator with a stacked title and description next to it, for import and upload flows.
• Progress bar: Each indicator is a thin bar, so the stepper reads as a segmented progress bar with titles.
• Segmented progress: A questionnaire style stepper with a segmented bar, a Back link, a step counter and a Next button.
• Vertical with description: A vertical timeline of order steps with titles, descriptions and a connecting line.
• Vertical: A compact vertical stepper with numbered indicators and a loading state.
• Multi step form: A complete onboarding wizard inside a Card with fields for each step and Back and Continue actions.

How to Install the Shadcn Stepper Component

Set up shadcn/ui in your project if you have not already, then add the Shadcn UI Kit registry to your components.json once:

{
  "registries": {
    "@shadcnuikit": "https://shadcnuikit.com/r/{name}.json"
  }
}

Then install a stepper variant by its name:

npx shadcn@latest add @shadcnuikit/stepper1

The same command works with pnpm dlx, yarn dlx and bunx --bun. Each variant has a copy button for every package manager, and the code is added to your project as plain React and Tailwind CSS that you can edit freely.

How to Use the Shadcn Stepper Component

Import the parts from components/ui/stepper. Give each StepperItem and its StepperContent the same step number.

import {
  Stepper,
  StepperContent,
  StepperIndicator,
  StepperItem,
  StepperNav,
  StepperPanel,
  StepperSeparator,
  StepperTitle,
  StepperTrigger,
} from "@/components/ui/stepper"

const steps = ["Cart", "Shipping", "Payment"]

export function Checkout() {
  return (
    <Stepper defaultValue={1} className="space-y-8">
      <StepperNav>
        {steps.map((title, index) => (
          <StepperItem key={title} step={index + 1}>
            <StepperTrigger>
              <StepperIndicator>{index + 1}</StepperIndicator>
              <StepperTitle>{title}</StepperTitle>
            </StepperTrigger>
            {index < steps.length - 1 && <StepperSeparator className="mx-2.5" />}
          </StepperItem>
        ))}
      </StepperNav>
      <StepperPanel>
        {steps.map((title, index) => (
          <StepperContent key={title} value={index + 1}>
            {title} form
          </StepperContent>
        ))}
      </StepperPanel>
    </Stepper>
  )
}

Why Use the Shadcn Stepper Component

• State handled for you: Completed, active and inactive states are derived from the active step, so you only track one number.
• Controlled or uncontrolled: Use defaultValue for simple flows or value and onValueChange when your own buttons or validation drive the steps.
• Flexible indicators: Show numbers, icons, dots or bars, and swap in a check or spinner per state with the indicators prop.
• Horizontal and vertical: The same parts work as a top navigation bar or a vertical timeline by changing the orientation.
• Theme aware: Colors come from your CSS variables, so every stepper follows your primary color in light and dark mode.

Common Stepper Use Cases

• Checkout flows: Cart, shipping and payment steps with a clear view of what is left.
• Onboarding wizards: Account, workspace and invite steps that collect details one screen at a time.
• Data imports: Upload, map and import steps with a loading indicator while files are processed.
• Surveys and quizzes: One question per step with a segmented progress bar and a step counter.
• Order tracking: A vertical timeline that shows placed, packed and shipped states.

Customizing the Shadcn Stepper

Every part accepts a className, merged with cn(). Style states with the data-state attribute on the part itself, or with the group-data-[state=completed]/step variant from any child of a step. Colors come from theme variables, so a palette from the free Theme Generator restyles every stepper at once.

For example, a larger icon indicator with an outline when inactive:

<StepperIndicator className="size-8 data-[state=inactive]:border data-[state=inactive]:bg-transparent">
  <UserRoundIcon className="size-4" />
</StepperIndicator>

Stepper Accessibility and Keyboard Support

StepperNav has role="tablist" and each trigger is a tab linked to its panel with aria-controls and aria-labelledby. The active trigger is the only one in the tab order, and the selected step is announced with aria-selected.

When an indicator is a bar with no visible number, keep the step number as visually hidden text, as the progress bar examples do.

Stepper Best Practices

• Keep flows short; three to five steps are easier to follow than ten.
• Use short, specific step titles such as Shipping or Payment.
• Mark steps the user cannot reach yet with disabled, and validate the current step before moving to the next one.
• Show a loading indicator while a step is saving instead of blocking the whole page.
• Switch to a vertical stepper or hide descriptions on small screens so titles do not wrap.
• Put form steps inside a Card and use Field for labels and errors.

Components Related to Stepper

Shadcn Stepper FAQ

Looking for something else? Browse all shadcn/ui components or ready-made UI blocks built with them.