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
stepper · base base · style base-lyraOpen under the product themeA setup flow in progress
Five steps, two complete, one current, two to come, driven by current.
stepper-setup-flow · base base · style base-lyraOpen under the product themeimport { 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.
stepper-with-descriptions · base base · style base-lyraOpen under the product themeimport { 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
fieldinstead. - The items are separate views the reader switches between at will, not a sequence taken in order.Use
tabsinstead. - You need one continuous measure of how far through a single task the reader is.Use
progressinstead.
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, soaria-livewould fire on unrelated renders. - A consumer who omits
labelships an unnamed list. The default and both examples set it, the recommended usage.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the stepper | Nothing to operate, so no tab stop; focus lands on the next interactive element. |
| Shift+Tab | Skips the stepper | Passed in reverse, moving focus to the previous interactive element. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below 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.