Stepper

Guides a user through a sequence of steps and indicates progress.

Choose the project type and confirm who the workflow belongs to.

Installation

$Terminal

npx shadcn@latest add https://sdk-components.thesqd.com/r/stepper.json

Usage

Drive `value` with state. Each `StepperItem.step` matches a `StepperContent.value` to render the right panel.

TSImport

import { Stepper } from "@/components/ui/stepper";

TSExample

"use client";

import * as React from "react";
import { Stepper } from "@/components/ui/stepper";

export function Example() {
  const [step, setStep] = React.useState(1);
  return (
    <Stepper
      value={step}
      onValueChange={setStep}
      steps={[
        { step: 1, content: "Step 1 content" },
        { step: 2, content: "Step 2 content" },
        { step: 3, content: "Step 3 content" },
      ]}
    />
  );
}

Composition

Anatomy of the Stepper primitive.

Stepper                           (single component — pass steps as data)
├── steps={[
│     { step?, title?, content?, indicator?, tooltip?, completed?, disabled?, loading? },
│     …
│   ]}
├── numbered                       (render the step number inside the dot)
├── orientation="horizontal" | "vertical"
├── indicators={{ active?, completed?, inactive?, loading? }}
└── ...rest                       (value / defaultValue / onValueChange / className)

Auto-emits StepperNav + StepperItem(+ Trigger + Indicator + Separator) per
step; StepperPanel + StepperContent for any step that has `content`.

Need a fully custom nav (e.g. multi-step form with header + side panel)?
The slot exports — StepperNav, StepperItem, StepperTrigger,
StepperIndicator, StepperSeparator, StepperTitle, StepperDescription,
StepperPanel, StepperContent — remain available as the escape hatch.

Default

Controlled horizontal stepper with previous and next actions.

Choose the project type and confirm who the workflow belongs to.

States

Per-step props let you preview completed, active, disabled, and loading states.

Inline title

Pass `numbered` and a `title` per step for compact horizontal flows.

Collapsed

Set `siblingCount` to collapse middle steps into a popover ellipsis — matches Pagination's UX for long sequences. `siblingCount={0}` keeps the rail at a max of 5 items (first, ellipsis, active, ellipsis, last).

Stacked (horizontal)

Pass `layout="stacked"` plus a `description` per step to stack the title + description under the indicator. Good for wizards that want labels visible at all times.

Stacked (vertical)

Pair `layout="stacked"` with `orientation="vertical"` for a side-by-side indicator + title/description list — onboarding sidebars and signup checklists.

Minimal

Pass `layout="minimal"` for a segmented progress bar — no dots or numbers, just brand-colored segments with a gradient on the active one and the current step listed to the side. Still fully clickable and `value`-driven like every other layout.

Step 3 of 6

Minimal (card edge)

Hide the label with `minimalShowLabel={false}` and absolutely position the stepper flush along the card's bottom edge. Drop the card's bottom border (`border-b-transparent`) so the gaps between segments don't reveal an outline underneath — the segmented bar becomes the bottom edge. Give any step a `tooltip` to label its segment on hover (or set `minimalTooltipTrigger="click"` to open it on click).

Build your organization

Complete the actions to unlock new features along the way.

3 steps to complete

Card

Pass `layout="card"` plus a `title` per step to render equal-width bordered cards with a "STEP N" eyebrow — the active card fills with the brand color. Matches the project-creation stepper on the dynamic form. Add `content` per step to render a panel below the cards (style it via `panelClassName`); mark a step `disabled` to gate it.

Give your project a title and tell us when you need it.

API Reference

Props exposed by the Stepper component.

Stepper

Prop	Type	Default	Description
`steps`	StepperStep[]	—	Step specs. Without this prop, Stepper stays compound (drop in StepperNav + StepperItem children manually).
`numbered`	boolean	false	Render the step number inside each indicator (otherwise the inactive dot is empty).
`layout`	"inline" \| "stacked" \| "minimal" \| "card"	"inline"	Layout style. "minimal" renders a segmented brand-colored progress bar (no dots/numbers) with the current step listed to one side. "card" renders equal-width bordered cards with a "STEP N" eyebrow above each `title`; the active card fills with the brand color.
`minimalShowLabel`	boolean	true	Minimal layout only — show or hide the step label next to the bar.
`minimalSegmentClassName`	string	—	Minimal layout only — extra classes on every segment. Pair `rounded-none` with `navClassName="gap-0"` to fuse the segments into one continuous bar (e.g. running flush along a card edge as its bottom border).
`minimalLabelSide`	"left" \| "right"	"right"	Minimal layout only — which side the step label sits on.
`minimalLabel`	(activeStep, total) => ReactNode	—	Minimal layout only — custom label renderer. Defaults to the active step's title, or "Step N of M".
`minimalTooltipTrigger`	"hover" \| "click"	"hover"	Minimal layout only — how a step's `tooltip` opens. `hover` shows a Tooltip; `click` opens a small Popover (the click still selects the step). Steps without a `tooltip` render plain segments.
`siblingCount`	number	—	Show this many step indicators on each side of the active step; remaining steps collapse into a popover ellipsis (like Pagination). `0` keeps the rail at its tightest — first, ellipsis, active, ellipsis, last (max 5 items). Omit to render every step inline.
`value`	number	—	Controlled active step (1-indexed).
`defaultValue`	number	—	Uncontrolled initial active step.
`onValueChange`	(step: number) => void	—	Fires when the active step changes.
`orientation`	"horizontal" \| "vertical"	"horizontal"	Layout direction of nav and separators.
`indicators`	{ active?, completed?, inactive?, loading? }	—	Override the rendered indicator content per state.
`navClassName`	string	—	Class names applied to the auto-emitted StepperNav.
`panelClassName`	string	—	Class names applied to the auto-emitted StepperPanel.

StepperStep

Prop	Type	Default	Description
`step`	number	—	1-indexed step number. Defaults to the array index + 1.
`title`	ReactNode	—	Inline label rendered next to the indicator (auto-emits a StepperTitle).
`content`	ReactNode	—	Panel content shown when this step is active.
`indicator`	ReactNode	—	Override the indicator content. When `numbered` is set on the parent, the step number is the default.
`tooltip`	ReactNode	—	Minimal layout only — tooltip for this step's segment. Opens on hover or click per the parent's `minimalTooltipTrigger`.
`completed`	boolean	—	Force the completed (checkmark) state.
`disabled`	boolean	—	Disable the trigger and dim the indicator.
`loading`	boolean	—	Show a spinner in the indicator.