# Stepper

A horizontal multi-step progress indicator with connectors.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/stepper
- Tier: Core and Pro

## Install

Stepper ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

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

- [Tabs](https://wunderui.com/components/tabs) for views of one object that people open in any order
- [Segment](https://wunderui.com/components/segment) for a switch between a few values of the same content
- [Timeline](https://wunderui.com/components/timeline) for events that already happened, with a time for each
- [Progress](https://wunderui.com/components/progress) for a single bar for how far a task has come

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | 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. |
| `Enter` or `Space` | Activates the focused step: `onStepClick` 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

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

- `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.
- `Step`: 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.
- `Dot`: 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.
- `Label`: 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.
- `Connector`: 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.
- `Description`: A 12 px line of text under a step's label in a vertical stepper. A horizontal stepper does not draw it.
- `StepperTrail`: 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.
- `CheckoutSteps`
- `Step`

## Best practices

### When to use

- Use it for a flow with a known number of ordered steps: checkout, onboarding, setup, order status. For switching between parallel views use Tabs or a Segment.

### 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.
- 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.
- 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.
- 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.
- 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.
- 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 make the step buttons the only way forward. They go to finished steps, and the forward action is your own Continue button.
- Don't pass a click handler or rely on the current step with the tinted look. Both are ignored there.

## API reference

### Stepper

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

### CheckoutSteps

| Prop | Type | Default | Description |
|---|---|---|---|
| current* | number |  | Index of the current step; the ones before it are done. |
| steps* | string[] |  | The step names, in order. |
| className | string |  |  |
| onStepClick | (index: number) => void |  | Called with the index of a finished step. Only done steps can be clicked, so people can go back but not skip ahead. |

### StepperTrail

| Prop | Type | Default | Description |
|---|---|---|---|
| current* | number |  | The index of the current step. The steps before it are done. Required. |
| steps* | string[] |  | The step names, in order. Required. |
| className | string |  | Extra classes on the list. |
| onStepClick | (index: number) => void |  | Called with the index of a finished step. Only finished steps can be clicked, so people can go back but not skip ahead. |

## Examples

### Size: dots of 24, 28 or 32 px

### Navigation: read-only, back to finished steps, or any step

### Vertical: with a connector, without one, dots, and a numbered list

### Steps: two, three or four

### Trail: numbered steps in one line

## In context

### Checkout: Back and Continue move the step

Continue and Back are the card's own buttons, and the stepper reports clicks on finished steps. In a narrow card the steps stack into a vertical stepper, switched by a container query.

### Setup: a vertical list where every step can be opened

Each step has a description. Later steps are clickable too, because the steps do not depend on each other.

### Order status: a read-only stepper that follows the order

The step comes from the data, so no step is a button. Pick a status under the card; Delivered marks every step done.

## For AI agents

`get_component("stepper")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
