Skip to content
WunderUI

Stepper

Pro

Shows where someone is in a flow of ordered steps, such as a checkout, setup or order, and lets them go back to finished steps.

Playground

  1. Done

Installation

Stepper comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  Stepper,
  CheckoutSteps,
  StepperProps,
  StepperStep,
  StepperTrail,
  StepperTrailProps,
} from "@wunderui/react"

Then use it:

tsx
import { useState } from "react"
import { Stepper } from "@/components/ui/stepper"

const STEPS = [
  { id: "shipping", label: "Shipping" },
  { id: "payment", label: "Payment" },
  { id: "review", label: "Review" },
]

export function Checkout() {
  const [step, setStep] = useState(1)

  return <Stepper steps={STEPS} currentStep={step} labelPosition="inline" onStepClick={setStep} />
}

Expected result: You see three steps in a row: Shipping with a check, Payment with a ringed 2 and Review with a plain 3, joined by lines. Click Shipping to go back to it.

When to use

Use Stepper for

  • A flow with a known number of ordered steps: a checkout, an onboarding, a setup
  • A status that moves in one direction, such as an order from Ordered to Delivered
  • A list of numbered instructions in a vertical layout, with a description for each

Use something else for

  • Tabs for views of one object that people open in any order
  • Segment for a switch between a few values of the same content
  • Timeline for events that already happened, with a time for each
  • Progress for a single bar for how far a task has come

Size

The size sets the dots to 24, 28 or 32 px. By default a horizontal stepper uses 24 px with the label beside the dot, 32 px with the label below, and a vertical one 28 px.

  1. Review

Without a step click handler the stepper only shows progress. With one, finished steps are buttons, and the all option lets people open any step except the current one.

  1. Cart, completed
  2. Shipping
  3. Payment
  4. Review

Vertical

A vertical stepper has room for a description under each label. It can draw a connector between the dots, show dots instead of numbers, or become a numbered list of instructions with the tinted look.

  1. Create the workspaceName it and pick a region.
  2. Invite your teamAdd up to 5 people for free.
  3. Add billing detailsChoose a plan and a card.
  4. LaunchReview and go live.

Steps

Two to five steps read well. Labels never wrap, so a row of steps needs the width of its labels; below that, use a vertical stepper.

Trail

StepperTrail is the compact form for a checkout or a short wizard: numbered steps in one line, separated by chevrons, with no connector lines or descriptions. A finished step shows a check on the indigo tint, the current one its number on solid indigo, an upcoming one a neutral outline. Only finished steps can be clicked, so people can go back but not skip ahead. It replaces CheckoutSteps.

Keyboard interactions

A clickable step is a native button, so it uses a button's keys. A step that can't be clicked is plain text, not a disabled button, and Tab skips it.

TaborShiftTab
Moves focus to the next or previous clickable step, in the order of the list. The current step and, by default, the upcoming steps are not tab stops and are skipped.
EnterorSpace
Activates the focused step: is called with its zero-based index.

Arrow keys, Home and End do nothing, and without a click handler or in the tinted look nothing is a tab stop. Focus stays on a step you activate, so move it into the new content yourself if needed.

Behavior and motion

What the stepper does with the current step, clicks, layouts, narrow screens, assistive technology and motion.

Current step
The current step is a zero-based index you control: earlier steps are finished, the step at the index is current, later ones upcoming. An index equal to the step count marks every step finished.
Three states
A step is finished, current or upcoming, derived from the current step. There is no error or disabled state, so show a problem in the step's content.
Clicks
The stepper never moves itself: the click handler gets the clicked index and you update the current step. Only finished steps are clickable by default, and the current step does nothing when clicked.
Layouts
Horizontal puts the dots in a row with a stretching connector and labels beside or below them. Vertical stacks the steps with a description under each label, and the tinted look is a numbered list.
Sizes
Sizes are 24, 28 or 32 px dots. The default depends on the layout: 24 px beside the label, 32 px below it, 28 px vertical.
Narrow screens
Labels never wrap, so a horizontal row is as wide as its labels and a narrower container cuts it off. Render a vertical stepper below that width, as the Checkout example does.
Hover and focus
Hovering a clickable step draws a 4 px indigo-tint ring around its dot. Keyboard focus draws the shared ring, around the whole button when horizontal and on the dot when vertical.
Assistive technology
The list is named Progress unless you pass a label, the current step is marked current and finished steps are announced as completed. Steps that can't be clicked are plain text, not disabled buttons.
Motion
The dot changes its fill, border and text colour, and a connector fills a bit slower. Nothing moves or scales.
Reduced motion
With reduced motion nothing changes in what you see. The colour changes are not movement and keep their short fade.

Anatomy

The figure marks a horizontal stepper with the label beside the dot, on its second of three steps: the list, a step, a finished dot, the current label and the connector after a finished step.

  1. Account, completed
  2. Plan
  3. Done
  • data-slot="stepper"

    The list: one ordered list named Progress (renamable) with one item per step, horizontal by default or vertical with a description per step. The current step is a zero-based index.

  • One item per step. It is a button while it can be clicked (finished steps by default, or any step but the current if all are navigable), otherwise plain text.

  • A round marker of 24, 28 or 32 px. Finished steps fill with the brand colour and a check, the current one has a thick indigo ring and its number, upcoming ones a thin border and their number.

  • The step's name in medium text on one line, 12 px horizontal and 14 px vertical. Dark for finished and current steps, tertiary for upcoming, with a hidden completed on finished ones.

  • Optional

    A 12 px line of text under a step's label in a vertical stepper. A horizontal stepper does not draw it.

  • Optional

    The 1 px line between two steps, filled with the brand colour once the step before it is finished. A vertical stepper draws it only when the connector option is on, which is the default.

  • data-slot="stepper-step"Optional
  • data-slot="stepper-trail"Optional

    The compact trail of a checkout or a short wizard: 20 px numbered steps in one line, separated by chevrons. A finished step shows a check on the indigo tint, the current one its number on solid indigo and an upcoming one a neutral outline. It replaces CheckoutSteps.

  • Optional

Best practices

  • Do

    Name each step with a short noun such as Shipping or Payment. Horizontal labels stay on one line, so keep them short, while the vertical layout has room for a description.

  • Do

    Put labels beside the dots above a form or card, and use the vertical layout with descriptions in a sidebar. Put labels below the dots when they are short and the row is narrow.

  • Do

    Stack the steps on a narrow screen. A horizontal stepper is as wide as its labels and doesn't wrap or scroll, so render a vertical one below that width, for example with a container query.

  • Do

    Make finished steps clickable with a click handler, and allow all steps only when they don't depend on each other. Only clickable steps are tab stops.

  • Do

    Show a validation problem in the step's content, with the step still current. The stepper has three states (finished, current, upcoming) and no error or disabled state.

  • Do

    Use the tinted look for a list of instructions, such as setting up two-step verification. It shows numbers only, has no current step and isn't clickable.

  • Don’t

    Don't use it for steps that can be done in any order. It marks one current step and the finished ones before it, which reads as a sequence.

  • Don’t

    Don't make the step buttons the only way forward. They go to finished steps, and the forward action is your own Continue button.

  • Don’t

    Don't pass a click handler or rely on the current step with the tinted look. Both are ignored there.

API reference

Stepper is a plain component, so the table lists every prop. Each step has an id, a label and an optional description. StepperTrail renders an ordered list and takes only the props listed under it.

The list: one ordered list named Progress (renamable) with one item per step, horizontal by default or vertical with a description per step. The current step is a zero-based index.

PropTypeDefaultDescription
steps requiredStepperStep[]—The steps in order: . is a unique key, the name, the line under the label in a vertical stepper.
currentStep requirednumber—The zero-based index of the current step. Earlier steps are finished and later ones upcoming. A value equal to marks every step finished. Ignored with .
onStepClick(index) => void—Called with the index of a clicked step. Set it to make steps clickable and update in it. Without it the stepper is plain text with no buttons. Ignored with .
orientation"horizontal" | "vertical""horizontal" (the default) puts the steps in a row, stacks them with a description under each label.
labelPosition"below" | "inline""below"Horizontal only. (the default) puts the label under the dot, beside it, which is shorter and suits a bar above a form.
navigable"done" | "all""done"Which steps can be clicked: (the default) the finished ones, every step except the current one.
size"lg" | "sm" | "md"—The dots: 24 px, 28 px, 32 px. Default: with , below the dot, vertical.
connectorbooleantrueVertical only. Draws the line between the dots. On by default; off leaves the line out.
numberedbooleantrueVertical only. Shows the step number in the dot; off shows a small dot. A finished step always shows a check. On by default.
appearance"progress" | "tinted""progress" (the default) shows progress. is a static numbered list in a vertical stepper: no current step, no clicks.
aria-labelstring—Names the list for screen readers. by default; name the flow, for example .
classNamestring—Extra classes for the list, for example to hide a layout in a narrow container.

The compact trail of a checkout or a short wizard: 20 px numbered steps in one line, separated by chevrons. A finished step shows a check on the indigo tint, the current one its number on solid indigo and an upcoming one a neutral outline. It replaces CheckoutSteps.

PropTypeDefaultDescription
steps requiredstring[]—The step names, in order. Required.
current requirednumber—The index of the current step. The steps before it are done. Required.
onStepClick(index) => void—Called with the index of a finished step. Only finished steps can be clicked, so people can go back but not skip ahead.
classNamestring—Extra classes on the list.

PropTypeDefaultDescription
current requirednumber—Index of the current step; the ones before it are done.
steps requiredstring[]—The step names, in order.
onStepClick(index) => void—Called with the index of a finished step. Only done steps can be clicked, so people can go back but not skip ahead.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("stepper")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.