---
title: "Stepper"
description: "Progress through a sequence of steps, drawn as a read-only indicator showing which steps are complete, which one is current, and which are still to come."
url: "https://opsinjs.pensievelabs.org/docs/components/stepper"
source: "https://opsinjs.pensievelabs.org/docs/components/stepper.md"
section: "Components"
status: "shipped"
kind: "component"
category: "navigation"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["wizard", "step indicator", "multi step"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="stepper"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured, neither the marker fills against the page nor the muted description ink against the surfaces this indicator sits on.&#x22;,
  &#x22;Nobody has listened to this in a screen reader, so whether aria-current and the sr-only \&#x22;Current step\&#x22; double-announce the current step is unchecked.&#x22;,
  &#x22;Forced colours and prefers-contrast: more are unhandled, so whether complete, current and upcoming stay apart once the platform substitutes its own fills is untested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="stepper" unbuilt="false" importPath="@/components/ui/stepper" dependencies="[&#x22;lucide-react&#x22;]" />

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

```tsx
<Stepper
  current={1}
  steps={[
    { label: "Your details" },
    { label: "Your preferences" },
    { label: "Review" },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="stepper" />

### A setup flow in progress [#a-setup-flow-in-progress]

Five steps, two complete, one current, two to come, driven by `current`.

<ComponentPreview name="stepper-setup-flow" kind="example" align="start" />

### Steps with supporting descriptions [#steps-with-supporting-descriptions]

Each step's optional `description` rides beneath its label in muted footnote
ink. Use it to clarify what a step covers, never to give an instruction: this
indicator cannot be operated.

<ComponentPreview name="stepper-with-descriptions" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Showing a reader where they are in a short, fixed sequence, beside the current step's own content.&#x22;,
  &#x22;Giving a multi step flow a sense of length, so the reader sees how many steps remain.&#x22;,
  &#x22;Reflecting progress the product already tracks, where each step's state comes from the product.&#x22;,
]"
  avoid="[
  { case: &#x22;You want several questions on one screen, with a bar of steps standing in for a real form.&#x22;, instead: &#x22;field&#x22; },
  { case: &#x22;The items are separate views the reader switches between at will, not a sequence taken in order.&#x22;, instead: &#x22;tabs&#x22; },
  { case: &#x22;You need one continuous measure of how far through a single task the reader is.&#x22;, instead: &#x22;progress&#x22; },
]"
/>

## Accessibility [#accessibility]

The root is an `<ol>` with `<li>` steps, so a screen reader announces a list of
known length, in order, and the current step carries `aria-current="step"`. State
never rests on colour alone: glyph, fill weight, border weight, label weight,
list position, and an sr-only "Completed", "Current step" or "Upcoming" all carry
it. The check glyph is `aria-hidden`, and the indicator takes no tab stop, since
it has nothing to operate. The audit fixed the root list's missing accessible
name: an optional `label` now forwards to the root `<ol>` as `aria-label`, set on
the default and both examples. When it is omitted, the attribute is dropped
rather than shipping empty.

**Residual items.**

* The upcoming marker's hairline border against the page is an unmeasured contrast pair. Meaning does not rest on it, because number, position, the sr-only word and label weight already carry upcoming state.
* No live region announces a change of `current`. The parent flow owns focus and announces each new page, so `aria-live` would fire on unrelated renders.
* A consumer who omits `label` ships an unnamed list. The default and both examples set it, the recommended usage.

<KeyboardTable
  name="stepper"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the stepper&#x22;,
    notes: &#x22;Nothing to operate, so no tab stop; focus lands on the next interactive element.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the stepper&#x22;,
    notes: &#x22;Passed in reverse, moving focus to the previous interactive element.&#x22;,
  },
]"
/>

<ContrastReport component="stepper" />

## Props interface [#props-interface]

<PropsTable name="StepperProps" />

`current` is a 0-based index into `steps`; the product owns position, the
component keeps no state of its own. An out-of-range or non-integer value is
clamped to the nearest real step and raises a development warning.
