Skip to content
opsinjs
Edit this page

Components

Stepper

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.

Usage

pnpm dlx shadcn@latest add @opsinjs/stepper

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { Stepper } from "@/components/ui/stepper"
<Stepper
  current={1}
  steps={[
    { label: "Your details" },
    { label: "Your preferences" },
    { label: "Review" },
  ]}
/>

Examples

Theme
Density
Text
Status
Accent theme
Accent
stepper · base base · style base-lyraOpen under the product theme

A setup flow in progress

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

Theme
Density
Text
Status
Accent theme
Accent
stepper-setup-flow · base base · style base-lyraOpen under the product theme
stepper-setup-flow.tsx
import { Stepper } from "@/components/ui/stepper"

export default function StepperSetupFlow() {
  return (
    <Stepper
      current={2}
      label="Example setup progress"
      steps={[
        { label: "Create your example account" },
        { label: "Confirm the sample email" },
        { label: "Choose demo preferences" },
        { label: "Add an example contact" },
        { label: "Finish the sample tour" },
      ]}
    />
  )
}

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.

Theme
Density
Text
Status
Accent theme
Accent
stepper-with-descriptions · base base · style base-lyraOpen under the product theme
stepper-with-descriptions.tsx
import { Stepper } from "@/components/ui/stepper"

export default function StepperWithDescriptions() {
  return (
    <Stepper
      current={1}
      label="Example walkthrough progress"
      steps={[
        {
          label: "Sample details",
          description: "Fictional profile fields, nothing here is stored.",
        },
        {
          label: "Example preferences",
          description:
            "How a walkthrough would ask about reminders, using placeholder copy only.",
        },
        {
          label: "Review the sample",
          description: "A read-only summary step in this demo flow.",
        },
      ]}
    />
  )
}

When to use it

Use it when

  • Showing a reader where they are in a short, fixed sequence, beside the current step's own content.
  • Giving a multi step flow a sense of length, so the reader sees how many steps remain.
  • Reflecting progress the product already tracks, where each step's state comes from the product.

Do not use it when

  • You want several questions on one screen, with a bar of steps standing in for a real form.Use field instead.
  • The items are separate views the reader switches between at will, not a sequence taken in order.Use tabs instead.
  • You need one continuous measure of how far through a single task the reader is.Use progress instead.

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.
KeyActionNotes
TabSkips the stepperNothing to operate, so no tab stop; focus lands on the next interactive element.
Shift+TabSkips the stepperPassed in reverse, moving focus to the previous interactive element.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from StepperProps in registry/bases/base/stepper.tsx.

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.