Stepper
A multi-step progress indicator and wizard navigation for shadcn on Base UI. It draws the steps of one task, keeps track of which are done, says which can be opened, and moves focus to the step a person lands on. Your form keeps its fields, validation and saving.
What it is
The stepper is a plugin: a component of cilo's own, installed as source into your project, so you read it, change it and own it. It comes as two items: the core, every part of a stepper in one file, and an optional compact overview for narrow screens.
- @cilo/stepper
- The core: Stepper, its list, items, triggers, indicators, titles, descriptions, separators, step panels and their headings, the finished state, and the useStepper, useStepperItem and useStepperArrival hooks.
- @cilo/stepper-overview
- A compact view: the current step's title and “Step 2 of 5” on a button that reveals the whole list, on the stock Collapsible.
A stepper is for ordered stages of one task: checkout, onboarding, a setup wizard, an order's progress. Peer views that are not in an order belong to Tabs, a quantity to Progress, and a number input's +/- buttons are a different kind of stepper.
Installation
With cilo's registry in your components.json (see Installation), add the core, and the overview if you want it:
npx shadcn@latest add @cilo/steppernpx shadcn@latest add @cilo/stepper-overview
The CLI writes components/cilo/stepper/stepper.tsx and components/cilo/stepper/stepper-overview.tsx, adds the stock Button and Collapsible the overview is drawn with, and installs @base-ui/react and class-variance-authority. The overview brings the core with it. Import the parts from where they landed:
import {Stepper,StepperList,StepperItem,StepperTrigger,StepperIndicator,StepperTitle,StepperDescription,StepperSeparator,StepperContent,StepperHeading,StepperDone,useStepper,useStepperItem,} from "@/components/cilo/stepper/stepper"
In a pnpm monorepo made with shadcn init --monorepo, the CLI adds those packages to packages/ui while the stepper's files land in your app, and pnpm keeps the app from seeing them. Add them to the app as well: pnpm --filter <app> add @base-ui/react class-variance-authority.
Anatomy
One Stepper holds one list of steps and one panel per step. A step is a StepperItem with a stable value; its panel is the StepperContent with the same value.
<Stepper defaultValue="shipping"><StepperList><StepperItem value="shipping"><StepperTrigger><StepperIndicator /><StepperTitle>Shipping</StepperTitle></StepperTrigger><StepperDescription>Where it goes</StepperDescription><StepperSeparator /></StepperItem>{/* one StepperItem per step */}</StepperList><StepperContent value="shipping"><StepperHeading>Shipping</StepperHeading>{/* the step's own fields */}</StepperContent><StepperDone><StepperHeading>Order placed</StepperHeading></StepperDone></Stepper>
- Stepper
- The root: holds the current value, the navigation rule, the orientation and whether the task is done.
- StepperList
- The ordered list (an ol), named “Steps” for screen readers unless you name it.
- StepperItem
- One step (an li) and its facts: completed, skipped, optional, invalid, visited, disabled.
- StepperTrigger
- What a person presses to open the step: a button, or a link through render.
- StepperIndicator
- The marker: the step's number, a check when completed, a minus when skipped, an alert when it needs attention; variant outline (default) or soft.
- StepperTitle
- The step's name.
- StepperDescription
- A line under the name, read as the trigger's description: a hint, a date, or why the step is locked.
- StepperSeparator
- The connector to the next step, drawn in the primary colour once its step is resolved.
- StepperContent
- The step's panel, shown while its step is current.
- StepperHeading
- The panel's heading (an h2), where focus lands when a person moves to the step.
- StepperDone
- What shows once the whole task is finished, in place of the panels.
Steps register themselves in the order they stand in the page, so a step added, removed or moved by your own logic renumbers the rest. Render the list once: a second list would register every step twice.
Usage
A three-step checkout: Next marks the current step completed and moves on, Back returns. Facts such as completed are yours, passed to each StepperItem; the stepper only reads them.
"use client"import * as React from "react"import { Button } from "@/components/ui/button"import {Stepper, StepperContent, StepperHeading, StepperIndicator, StepperItem,StepperList, StepperSeparator, StepperTitle, StepperTrigger, useStepper,} from "@/components/cilo/stepper/stepper"const STEPS = [{ value: "shipping", title: "Shipping" },{ value: "payment", title: "Payment" },{ value: "review", title: "Review" },]function Footer({ onComplete }: { onComplete: (value: string) => void }) {const { value, isFirst, isLast, prev, next } = useStepper()return (<div className="flex justify-end gap-2"><Button variant="outline" disabled={isFirst} onClick={() => prev()}>Back</Button><Buttondisabled={isLast}onClick={() => {onComplete(value)next()}}>Next</Button></div>)}export function CheckoutSteps() {const [completed, setCompleted] = React.useState<Record<string, boolean>>({})return (<Stepper defaultValue="shipping"><StepperList>{STEPS.map((step, i) => (<StepperItem key={step.value} value={step.value} completed={completed[step.value]}><StepperTrigger><StepperIndicator /><StepperTitle>{step.title}</StepperTitle></StepperTrigger>{i < STEPS.length - 1 ? <StepperSeparator /> : null}</StepperItem>))}</StepperList>{STEPS.map((step) => (<StepperContent key={step.value} value={step.value}><StepperHeading>{step.title}</StepperHeading></StepperContent>))}<Footer onComplete={(value) => setCompleted((c) => ({ ...c, [value]: true }))} /></Stepper>)}
Any component inside Stepper reads it with useStepper, so a footer of your own, outside the list and the panels, drives it.
Navigation
The navigation prop sets which steps a person may open from the list. It never stops your own code: next, prev and setValue move wherever you send them.
- linear (default)
- A step opens once every enabled step before it is completed or skipped. Earlier steps stay open. A locked step stays focusable, announced as unavailable, and is not dimmed.
- any
- Every enabled step can be opened in any order, as in a form of sections filled at will.
- none
- A report: the steps are text, not buttons, and nothing can be pressed. The current one is announced as “Current step”. Use it for an order's or a job's progress.
A locked step should say why. Read reachable from useStepperItem inside its item and show a StepperDescription while it is false; the trigger reads it to screen readers as its description:
function LockReason({ previous }: { previous: string }) {const { done } = useStepper()const { reachable } = useStepperItem()if (done || reachable !== false) return nullreturn <StepperDescription>Complete {previous} first</StepperDescription>}
Step facts and states
Each StepperItem takes the facts of your workflow as booleans. The stepper draws them, announces them and derives the step's state from them.
- completed
- The work of the step is accepted. Its marker becomes a check, its connector fills, and “Completed” is read after its name.
- skipped
- An optional step left out. A minus marker and “Skipped”; under linear navigation it unlocks the next step as completed does.
- optional
- The step may be skipped. Nothing is drawn: say “Optional” in its title or description, where everyone sees it.
- invalid
- The step needs attention. An alert marker and “Needs attention”; it wins over completed and skipped, and never locks a later step.
- visited
- The person has been there. Only a data-visited attribute, for a style of your own.
- disabled
- The step does not apply. It cannot be opened, next and prev pass over it, and a later step does not wait for it.
The state a step is drawn in follows one order: current, then completed, then skipped, then upcoming. A step that is current and also completed is still drawn as current, with its check.
Moving between steps
useStepper, called anywhere inside Stepper, gives what your own buttons need:
value, index, count- The current step's value, its place from 0, and how many steps there are. Before the steps have registered (the server render) index is -1 and count is 0.
steps- Every step with its facts, index, whether it is current, whether it can be opened (reachable), and its state.
isFirst, isLast- Whether prev or next would stop here; disabled steps at either end do not count.
next(), prev()- Move to the next or previous enabled step and return its value, or undefined at the end. They do nothing while the task is done or the value names no step.
setValue(value)- Move to any step, without a navigation check.
isReachable(value)- Whether that step can be opened now under the navigation rule; safe to call while rendering.
navigation, orientation, done- The root's props as they are now.
Completing a step and moving in one handler works: call your own setter for completed, then next(). setValue(x) followed by next() in the same handler lands after x.
Controlled value
Give defaultValue and the stepper keeps the current step itself. Give value and onValueChange to keep it yourself, in state, a store or the URL. A Stepper takes one of the two, never both.
const [step, setStep] = React.useState("shipping")<Steppervalue={step}onValueChange={(value, { reason }) => {// reason: "trigger" | "next" | "prev" | "set" | "removed"setStep(value)}}>…</Stepper>
onValueChange says why the value changes: trigger (a step was pressed), next, prev, set (setValue), or removed (the current step left the list and the nearest enabled step took its place). A controlled stepper only asks: nothing moves until you pass the new value back, so you can refuse or redirect a move.
Finishing
Set done when the whole task is finished. The panels hide, StepperDone shows, no step is current and every step locks; the list stays, so the person still sees what they went through.
const [done, setDone] = React.useState(false)<Stepper defaultValue="shipping" done={done}>…{done ? null : <Footer onFinish={() => setDone(true)} />}<StepperDone><StepperHeading>Order placed</StepperHeading><StartOver onReset={() => setDone(false)} /></StepperDone></Stepper>
To start again or edit an answer, clear done and, if needed, move with setValue. Leaving done from a button inside StepperDone hands focus back to the current step's heading.
Focus and accessibility
- After a move the stepper makes (a step pressed, next, prev, setValue), focus goes to the new step's StepperHeading, or to its panel when it has none. Give every panel a heading.
- Focus never moves on the first render or when your code changes value from outside. setValue(value, { focus: false }) and next({ focus: false }) move without it, for a step restored from storage or the URL.
- A move a controlled parent takes up late moves focus only if the person has not pressed or typed anything since, and only within 3 seconds.
- Turning done on moves focus to StepperDone's heading when focus was inside the stepper or nowhere, so a Finish button lands there; a done set by a data load while the person works elsewhere leaves them be.
- If an outside change hides the panel holding focus, or removes the step whose trigger had it, focus goes to the step shown next, never to the page.
- The current trigger carries aria-current="step"; a locked or disabled one is aria-disabled and stays in the tab order, so its reason can be read.
- Completed, skipped and needs attention are spoken after the step's name; the current step is marked by an outline as well as colour.
A StepperDescription can sit beside the trigger or inside it. Inside, it is kept out of the trigger's name and still read as its description, so it is never read twice.
Steps as links
When every step has its own address, render the trigger as a link. The stepper keeps the link only while the step can be opened: a locked, disabled or finished step renders a plain button, so it can never navigate.
<StepperTrigger render={<a href={"#step-" + step.value} />}><StepperIndicator /><StepperTitle>{step.title}</StepperTitle></StepperTrigger>
A Ctrl, Cmd or Shift click, or a link with a target, opens the step elsewhere and leaves this page where it is. When the value comes from the address, check it before taking it:
// Inside <Stepper>: a value from the URL or storage moves no focus.const { setValue, isReachable } = useStepper()if (isReachable(saved)) setValue(saved, { focus: false })
Before hydration the server cannot know which steps are locked and renders every enabled step's link, so a route that must not open early checks its own rule.
Compact overview
On a phone a row of steps does not fit. The overview shows the current step and its position on one full-width button, and the whole list under it on demand. It holds the stepper's one list, so nothing is registered twice.
import {StepperOverview,StepperOverviewContent,StepperOverviewTrigger,} from "@/components/cilo/stepper/stepper-overview"function CurrentTitle() {const { value } = useStepper()return STEPS.find((step) => step.value === value)?.title}<Stepper defaultValue="shipping" orientation="vertical"><StepperOverview><StepperOverviewTrigger><CurrentTitle /></StepperOverviewTrigger><StepperOverviewContent><StepperList>{/* the one list of steps */}</StepperList></StepperOverviewContent></StepperOverview>{/* panels and footer */}</Stepper>
- StepperOverview
- The stock Collapsible. open, defaultOpen and onOpenChange(open, { reason, event }); reason is trigger-press, none, or item-press for a step chosen inside. closeOnSelect (true by default) closes it once a chosen step has opened.
- StepperOverviewTrigger
- A ghost Button at least 44px tall: your children (the current title), then the position, then a chevron. countLabel(position, count) replaces “Step n of N”; no position shows while done.
- StepperOverviewContent
- The panel that holds the StepperList. It always stays mounted, so the steps register while it is closed.
To show the full list on wide screens and the overview on a phone, hold the panel open from md up with the stock useIsMobile hook and hide the trigger there:
const isMobile = useIsMobile()const [open, setOpen] = React.useState(false)<StepperOverview open={isMobile ? open : true} onOpenChange={setOpen}><StepperOverviewTrigger className="md:hidden">…</StepperOverviewTrigger><StepperOverviewContent><StepperList>…</StepperList></StepperOverviewContent></StepperOverview>
A closed panel is hidden with the hidden attribute, which Tailwind hides with !important, so md:block cannot show it; hold it open instead. As with the stock Sidebar, the server renders the wide layout and a phone collapses it after hydration.
Orientation and layout
orientation is horizontal (the default) or vertical. Horizontal lays the steps in a row with connectors between them and the panel under the list; vertical stacks them with the list beside the panel. Three or more steps with titles need room: below md, switch to vertical with the stock useIsMobile hook, or use the overview.
Layout is yours to change with className on any part: a width for a vertical list, flex-col on the root to keep the list above the panel in both orientations. Changing the orientation keeps the current step, the drafts and every fact.
Labels and translation
The stepper writes five words of its own, in English: the list's name and the statuses read after a step's name. Replace any of them through labels; the ones you leave out keep their default.
<StepperdefaultValue="kontakt"labels={{list: "Schritte",current: "Aktueller Schritt",completed: "Erledigt",skipped: "Übersprungen",invalid: "Prüfen",}}>
An aria-label on StepperList wins over labels.list. The defaults are exported as STEPPER_LABELS. The overview's position is a function, countLabel, so a translated overview sits in a client component.
Styling
The parts carry shadcn's data-slot names and data attributes for their state, so a style of your own targets them without new props:
- data-slot
- stepper, stepper-list, stepper-item, stepper-trigger, stepper-indicator, stepper-title, stepper-description, stepper-separator, stepper-content, stepper-heading, stepper-done; the overview's stepper-overview, -trigger, -content.
- Stepper
- data-orientation, data-navigation, data-done.
- StepperItem
- data-state (current, completed, skipped, upcoming), data-current, data-completed, data-skipped, data-optional, data-invalid, data-visited, data-disabled, data-locked, data-orientation.
- StepperTrigger
- data-locked, data-disabled (not under navigation none), aria-current, aria-disabled.
- StepperIndicator
- data-variant, data-current, data-completed, data-skipped, data-invalid.
- StepperSeparator
- data-orientation, data-resolved, data-skipped, data-invalid.
- StepperContent
- data-state: current or hidden.
Inside an item, the group/stepper-item group styles its children by its state, as in group-data-current/stepper-item:font-semibold on a title. Colours come from your theme's tokens, so a palette changes them all. StepperIndicator's variant picks the marker look: outline (default) or soft. Both use primary and primary-foreground for completed markers and resolved connectors, a primary ring on the current marker, border for connectors still ahead and destructive for a step that needs attention. outline draws the other markers with a border line; soft fills an upcoming marker with muted and foreground and the current one with primary and primary-foreground.
API reference
Every part also takes the props of the element it renders (className, ids, aria and event props) and a ref.
Stepper
value / defaultValue: string- The current step, held by you or by the stepper. One of the two is required.
onValueChange(value, { reason })- Called on every move; reason is trigger, next, prev, set or removed.
navigation- linear (default), any or none.
orientation- horizontal (default) or vertical.
done: boolean- The task is finished: panels hide, StepperDone shows, every step locks. Default false.
labels- Any of list, current, completed, skipped, invalid.
StepperItem
value: string- The step's stable id, unique in its stepper. Required.
completed, skipped, optional, invalid, visited, disabled- The step's facts, all false by default.
StepperTrigger, StepperHeading
render- Render another element: a link, a router Link, a stock Button. On a locked, disabled or finished step a render that could navigate is dropped; any other stays, without its onClick.
StepperTrigger is a button (a span under navigation none) and StepperHeading an h2; both take render the Base UI way.
StepperContent
value: string- The step this panel belongs to. Required.
keepMounted: boolean- Keep the panel in the page, hidden, while another step is current, so an uncontrolled field keeps what was typed. Default false.
StepperIndicator
variant- outline (default) or soft. outline borders every marker and fills a completed one with primary; soft fills an upcoming marker with muted and the current one with primary too, keeping the current step's ring, and an invalid step stays destructive even when current. Its classes are exported as stepperIndicatorVariants.
Children replace the number, check, minus or alert, as an icon of your own for each step; leave it empty for the default.
useStepperItem, useStepperArrival
useStepperItem, inside a StepperItem, returns that step: value, index, current, reachable (null until the steps register), state, its facts and descriptionIds. useStepperArrival(listener) runs after a move the stepper made has landed and its panel has taken focus, with the value, the reason and, for a pressed step, the trigger and the event; the overview closes with it.
import { useStepperArrival } from "@/components/cilo/stepper/stepper"// Inside <Stepper>: runs after a move the stepper made has landed.useStepperArrival(({ value, reason, trigger }) => {analytics.track("step", { value, reason })})
Troubleshooting
The stepper reports misuse in the console once per problem; nothing breaks, but the steps will not behave as meant until it is fixed.
- “Stepper: two steps share the value”
- Two StepperItems have the same value. Give every step its own; a value is the step's id, not its title.
- “Stepper: no step has the value”
- value or defaultValue names no StepperItem, so no step is current and next() does nothing. Check the spelling, or that the step is rendered.
- “Stepper: current step … is not reachable under linear navigation”
- The value moved past a step that is neither completed nor skipped. Mark the earlier step first (set completed before next() in the same handler works), or use navigation any.
- “Stepper: every step unregistered”
- The StepperList left the page, so there are no steps and Back and Next stop. Keep the list mounted and hide it with CSS, or hold it in the overview.
- “useStepper must be used within a <Stepper />”
- A part or the hook is rendered outside a Stepper. Every stepper part, and any component calling useStepper, goes inside one.
- “Module not found: Can't resolve '@base-ui/react/use-render'”
- A pnpm monorepo: add @base-ui/react and class-variance-authority to the app, as the note under Installation says.