Stepper

Install

pnpm exec vegastack-design verify stepper

pnpm dlx shadcn@4.21.0 add @vegastack/stepper

Usage

import { Stepper } from "@/components/ui/stepper";

<Stepper
  aria-label="Import"
  steps={[
    { id: "upload", label: "Upload file", state: "complete" },
    { id: "map", label: "Map columns", state: "current" },
    { id: "review", label: "Review", state: "upcoming" },
  ]}
/>;

Not Tabs. role="tab" announces "tab 2 of 6" and implies free navigation between peers — actively misleading for a flow where step 4 is unreachable until step 3 validates. Stepper is an ordered list with aria-current="step", which is what a wizard actually is. Where a full step list is too heavy, use Progress directly — though below collapse this component already becomes one.

It has no Back and Next, and most uses need none. Reach for Stepper alone when the process is driven by the system and read by a person — an order or delivery tracker, a deployment pipeline, an application's status, a long import running on a server. When a person drives the flow and it needs controls, guards and step bodies, use MultiStepForm, which composes this component and owns the action row.

Scope

It communicates the process, and nothing else.

The refusal message is the one to read twice. Stepper deliberately does not render it: the only place it could sit is under the current step's label, which in a horizontal rail is a one-column-wide ribbon and in the collapsed form does not exist. A reason belongs next to the button it refuses.

Anatomy

Examples

When the host drives it

The buttons below belong to the page, not to Stepper — it renders none. They sit right-aligned with no divider, Back on variant="secondary", which is how MultiStepForm draws its action row too. For anything more than a demo, use that component rather than wiring this by hand.

Every state

Seven states, and the two that are coloured are coloured because something needs the user. current alone takes the solid primary fill and a medium-weight label; complete is the same hue muted — a check on a light primary tint, with the connector behind it in the same tone — and upcoming is an outline with a muted label. Progress is not success: a rail of green leaves nothing louder for the step that has actually failed. loading is the state an async advance gate occupies while it runs, and skipped records a step passed over rather than one that failed.

Error state

The state every hand-rolled stepper forgets: a step that failed after completion. Its node takes the destructive fill, its label the family's -text ink, and the rail behind it does not fill — you have not passed it. When the step that failed is the one the user is on, set current: true alongside state: 'error': it keeps aria-current="step" and the step count while showing the error (MultiStepForm does this for you).

Collapsing to a summary

Below collapse the rail becomes the current step's name, its position, and a Progress bar. It is a container query, not a viewport one, so a rail inside a narrow dialog collapses on a wide screen too. Both examples below are the same component with the same props; only the box around them differs.

Sizes

Inline labels

labelPosition="inline" sets each label beside its node with the connector running on from it — a compact rail for a card header. The DOM and the reading order are identical to the default.

Vertical and navigable

orientation="auto" (the default) switches to vertical at verticalFrom steps, because a rail long enough to crush its own labels reads better down the page. In navigable mode, completed, skipped and error steps become real buttons for revisiting — the whole step, node and label together, is one target, so the circle is as clickable as the text — a failed step is exactly the one the user needs to get back to; current, upcoming, and disabled steps never do.

A rail wider than its container

Every step keeps a readable minimum width, so six steps in a narrow container scroll sideways instead of crushing their labels (pass collapse={false} to keep the rail at every width), and the list scrolls the current step into view — on first render too — without moving the page. Revisitable and current steps share one step box — same padding — and the current label's bold width is reserved, so the rail never shifts as the current step moves. A revisitable step shows only the standard hover fill across its node and label, with no press motion.

API Reference

Step

Accessibility

• An <ol> labelled by aria-label, with aria-current="step" on the current item — never tab semantics. A loading step is still the current step.
• Step state is carried by the node's glyph and visually hidden text ("Completed", "Checking", "Needs review", "Needs attention", "Skipped"), never colour alone.
• When the current step changes, focus moves to the new step — not the first form field, and never on initial mount. Below the collapse width the rail is not laid out, so focus lands on the summary instead.
• The compact summary is a real progressbar, named by the current step.
• A navigable step is one Button wrapping its node and label, named by the label and its state, so it clears the 24px touch floor and takes the system's single focus outline. The connector is decorative and never part of the target.

Do / Don't