Stepper

A steps indicator that shows where someone is in a multi-step flow, what is done, and where something failed.

When to use

• Onboarding, checkout, setup, and deploy flows with a fixed order of steps.
• Above (horizontal) or beside (vertical) the step content, driven by your own current index.
• Not for an unordered setup list: use OnboardingChecklist. Not for switching between peer views: use Tabs. For page hierarchy use Breadcrumb.

Usage

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

h(Stepper, {
  label: "New listing",
  current: step,
  onStepSelect: setStep,
  steps: [
    { id: "details", label: "Listing", description: "Title, size and rent" },
    { id: "verify", label: "Verification", description: "Name verified with eID" },
    { id: "publish", label: "Publish", error: step === 2 && failed ? "Photos missing" : undefined },
  ],
});

Props

Prop	Type	Default	Description
steps	{ id: string; label: string; description?: string; error?: string }[]	—	Required. error marks a step as failed and replaces its description.
current	number	—	Required. Index of the step in progress; steps.length marks the flow complete.
orientation	"horizontal" | "vertical"	"horizontal"	Layout.
onStepSelect	(index: number) => void	—	Makes completed steps selectable by click or keyboard. Without it the stepper is read only.
details	"all" | "current"	"all"	current shows only the active step's description (errors always show).
compact	boolean	false	Markers only, with the current label underneath. Horizontal steppers switch to this below 30rem on their own.
label	string	"Progress"	Accessible name.
completeLabel	string	"All steps complete"	Announced, and shown in the compact caption, when every step is done.
className	string	—	Extra class.

Notes

• The current step has aria-current="step" and changes are announced through a polite live region. With onStepSelect, arrow keys move between completed steps (RTL aware).
• Markers morph between number, check, and alert, and connectors fill on a spring; reduced motion updates instantly.
• Reads --accent, --accent-tint, --accent-ink, --on-accent, --red, --surface, --line, --line-strong, --ink, --ink-2, --ink-3.