Skip to content
werewolf-ui
Components

Stepper

Shows the steps of a flow in order and where the user is (checkout, onboarding, setup). Completed steps are buttons that go back to that step; upcoming steps cannot be reached from here. Use Tabs for switching views, not for a sequence.

Preview

  2. 2Shipping, current step
  3. 3Payment, not reached

Props

  • orientation
import { Stepper } from "@/components/ui/stepper"

<Stepper steps={checkoutSteps} current={1} onStepSelect={goToStep} />

Usage

When to use

  • Show where someone is in an ordered flow such as checkout, onboarding or setup.
  • Let someone return to a completed step without opening upcoming steps early.

When not to use

  • Switch between views of the same content. Use Tabs.
  • Show how much work is complete without naming sequential steps. Use Progress.
  • Navigate between pages or sections. Use Sidebar or BottomNav.

Variants

orientation

Row or column. Use vertical below md when labels do not fit, or in a side column.

    2. 2Shipping, current step
    3. 3Payment, not reached

    horizontaldefault

    2. 2Shipping, current step
    3. 3Payment, not reached

    vertical

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

<Stepper steps={checkoutSteps} current={1} onStepSelect={goToStep} />
<Stepper orientation="vertical" steps={checkoutSteps} current={1} onStepSelect={goToStep} />

Examples

Checkout

  2. 2Shipping, current step
  3. 3Payment, not reached
import { Stepper } from "@/components/ui/stepper"

<Stepper current={1} steps={checkoutSteps} onStepSelect={goToStep} />

Vertical with descriptions

  1. 1Account, current stepEmail and password
  2. 2Team, not reachedInvite people
import { Stepper } from "@/components/ui/stepper"

<Stepper orientation="vertical" current={0} steps={setupSteps} />

Do and don't

Do

  • Keep labels to one or two words.
  • Use 3 to 7 steps; more needs grouping.
  • Show the step count in the page heading too (Step 2 of 4) when the Stepper is hidden on small screens.

Don't

  • Do not use Tabs for a sequence the user must follow in order.
  • Do not use as navigation to steps the user has not reached.

Props

NameTypeValuesDefaultDescription
steps required{ id: string; label: string; description?: string; status?: "error"; icon?: React.ReactNode }[]--The steps in order. icon replaces the number in a current or upcoming step. status error overrides the computed visual state of that step.
current requirednumber--Zero-based index of the current step. Steps before it are complete.
orientationenumhorizontal | verticalhorizontalRow or column. Use vertical below md when labels do not fit, or in a side column.
onStepSelect(index: number) => void--Called with the index when a completed step is activated, to go back to it. Required by the type when current is greater than zero, because an earlier step can be activated.
statusLabels{ completed?: string; current?: string; upcoming?: string; error?: string; goBack?: (label: string) => string }--Words added to each step's accessible name, as {label}, {status}: { completed, current, upcoming, error }. Defaults: completed, current step, not reached, has an error. Vietnamese: đã xong, bước hiện tại, chưa đến, có lỗi. goBack names a completed step button: EN `{label}, completed, go back to this step`, VI `{label}, đã xong, quay lại bước này`.

Slots

NameRequiredDescription
stepIconnoOptional custom icon per step, replacing the number (not the check or error icon).

Anatomy

PartDescription
rootThe ol that lays out the steps in a row or a column.
stepOne li: indicator, label, optional description.
indicatorThe 24px circle with the step number, a check when complete, or a warning icon on error.
labelThe step title, font-size-md, medium weight on the current step.
descriptionOptional secondary line under the label.
connectorThe line between two indicators; accent once the earlier step is complete.

Accessibility

Role: list

KeysAction
TabMoves to the next completed step (a button). The current and upcoming steps are not focusable.
Enter / SpaceGoes back to the focused completed step through onStepSelect.
  • An ordered list. The current step has aria-current="step" and sets data-current.
  • A completed step is a button named EN `{label}, completed, go back to this step`, VI `{label}, đã xong, quay lại bước này`.
  • Each step's accessible text includes its state word (completed, current, upcoming, error) from statusLabels, not only the icon or color.
  • The connector lines are decorative (aria-hidden).
  • Steps with an error show a danger icon and the word from statusLabels.error.

Install

npx werewolf-ui add stepper

Run npx werewolf-ui init once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See Installation for requirements and the alternative registry setup.