Stepper
A progress indicator for sequential flows: onboarding, checkout and multi-step dialogs. Each step derives its state from a single active value, and each bar fills as you advance.
Try it yourself. This one is live, and its code is right below.
Installation#
Usage#
"use client"
import * as React from "react"
import {
Stepper,
StepperItem,
StepperTrigger,
StepperIndicator,
StepperTitle,
} from "@/components/ui/stepper"
export function Example() {
const [step, setStep] = React.useState(1)
return (
<Stepper value={step} onValueChange={setStep}>
<StepperItem step={1}>
<StepperTrigger>
<StepperIndicator />
<StepperTitle>Account</StepperTitle>
</StepperTrigger>
</StepperItem>
<StepperItem step={2}>
<StepperTrigger>
<StepperIndicator />
<StepperTitle>Confirm</StepperTitle>
</StepperTrigger>
</StepperItem>
</Stepper>
)
}Anatomy#
import {
Stepper,
StepperItem,
StepperTrigger,
StepperIndicator,
StepperTitle,
StepperDescription,
StepperSeparator,
StepperPanels,
StepperPanel,
} from "@/components/ui/stepper"
<Stepper>
<StepperItem step={1}>
<StepperTrigger>
<StepperIndicator />
<StepperTitle />
<StepperDescription />
</StepperTrigger>
<StepperSeparator />
</StepperItem>
</Stepper>
<StepperPanels value={step}>
<StepperPanel step={1} />
</StepperPanels>Orientation#
Orientation is set on the root. horizontal lays the steps in a row of bars; vertical stacks them as numbered circles with the connector running down the indicator column.
Circles#
Bars are the default. For a numbered rail, set variant="outline" (a ringed circle with a halo on the current step) or variant="solid" (flat fills), and add a StepperSeparator to every item but the last so the line fills as you advance.
With descriptions#
Pair each StepperTitle with a StepperDescription in a vertical stack. Vertical orientation gives the supporting copy room to breathe.
Density#
Density retunes the indicator size, connector geometry, and text, without touching color or radius. comfortable suits onboarding; compact fits dense app UI and dialogs.
Loading & disabled#
Set loading on the active step while it validates or submits: its bar pulses (on circles the number turns into a spinner). Mark unreachable steps disabled to block selection and mute them.
In a dialog#
The headline use case. Reach for DialogStepper (from @/components/ui/dialog). Place it first, above the title: the bars name each screen, so the bodies need no heading of their own, and it inherits the dialog's density. Put the step bodies in StepperPanels with the same value: the dialog grows or shrinks to each step and the body slides in from the side you moved. Cancel turns into Back after the first step, the last step names its action, and a final panel confirms the result before the dialog closes.
API reference#
Stepper
The root: holds the active step and renders a <div role="group">. Forwards all native <div> props except onChange; every part accepts className, merged last.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | - | The active step (1-based), controlled. Pair with onValueChange. |
| defaultValue | number | 1 | The initial active step (1-based), uncontrolled. |
| onValueChange | (step: number) => void | - | Fires when a StepperTrigger selects its step. |
| variant | "outline" | "solid" | "bars" | "bars" | bars draws each step as a progress bar over its label, horizontal only (a vertical stepper falls back to outline); outline is a ringed circle with a halo on the active step; solid fills every state flat. |
| orientation | "horizontal" | "vertical" | "horizontal" | A row with the label under each circle, or a column with the label beside it. |
| density | "comfortable" | "compact" | - | Indicator size (28 or 24px) and text tier. Inherits the nearest DensityProvider when omitted. |
| Data attribute | Description |
|---|---|
| data-orientation | horizontal or vertical. |
| CSS variable | Description |
|---|---|
| --step-size | The indicator diameter, set per density (1.75rem or 1.5rem); every connector offset derives from it. |
StepperItem
One step. Derives its state from the root's active value and its own step. Forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| step* | number | - | This step's 1-based position. |
| completed | boolean | - | Forces the completed state regardless of the active step, for non-linear flows. |
| disabled | boolean | false | Blocks selection through the trigger and mutes the step. |
| loading | boolean | false | Swaps the indicator glyph for a Spinner. |
| Data attribute | Description |
|---|---|
| data-state | completed (before the active step), active or inactive. |
| data-disabled | Present when disabled. |
| data-loading | Present when loading. |
StepperTrigger
The clickable region that selects its step; omit it for a read-only progress indicator. Renders a <button> and forwards all its props; sets aria-current="step" on the active step.
| Prop | Type | Default | Description |
|---|---|---|---|
| asChild | boolean | false | Renders onto the child element via Radix Slot instead of a <button>. |
| static | boolean | false | Kept for compatibility; controls no longer scale on press. |
StepperIndicator
The numbered circle: the step number (or children as a custom resting glyph), a spinner while loading. When the step completes the glyph morphs into a check (both share one cell and trade scale, opacity and blur) instead of being swapped, and morphs back if you return to it. Forwards all native <span> props.
StepperTitle
The step's label, which turns to full ink once active or completed. Forwards all native <span> props.
StepperDescription
A muted secondary line under the title. Forwards all native <span> props.
StepperSeparator
The connector to the next step, placed last in every item but the last; its fill grows when the step completes (and drains when you step back) on the same settle curve as StepperPanels, so the line and the body arrive together. Hidden from assistive tech. Forwards all native <div> props.
StepperPanels
The viewport for the step bodies, a sibling of the Stepper. Built on the shared useMorphBox (see Morphing), it tweens its height to the incoming step and slides the new body in from the side you travelled on the same duration and curve, so resize and slide read as one move (a short fade under reduced motion). When the step change drops focus, it lands on the new step's first control. Forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | number | - | The step on show. Pass the same value as the Stepper; comparing it with the last one gives the slide direction. |
StepperPanel
One step's body, rendered only while its step matches the panels' value. Keep field values in your own state so Back returns them filled. Forwards all native <div> props.
| Prop | Type | Default | Description |
|---|---|---|---|
| step | number | - | The 1-based step this body belongs to. |