ComponentsNavigation

Stepper

Shows position and status in an ordered process — import wizards, onboarding, approvals, checkout. Horizontal or vertical, four variants, error / skipped / loading states and clickable completed steps.

components/stepper.tsxtheme · material · accent · density · font

Step 1 of 4, Uploadcontacts-nov.csv, Completed
Step 2 of 4, Map columns12 of 14 matched, Current
Step 3 of 4, ReviewDuplicates and errors
Step 4 of 4, Import

Step 2 of 4Map columns

Installation

$ pnpm add @vamos-ui/react

The whole kit as one package — get updates by bumping the version. Add the styles to globals.css: @import "@vamos-ui/react/styles.css";

Usage

import { Stepper } from "@vamos-ui/react";

<Stepper value={1} steps={[
  { title: "Upload" }, { title: "Map columns" }, { title: "Review" }, { title: "Import" },
]} />

Each step's name includes its position and status: "Step 2 of 4, Map columns, Current"; the current step has aria-current="step".

Examples

Vertical with content (HR onboarding)

<Step> children render under the current step. Moving between steps doesn't move focus — focus your step's heading.

Step 2 of 4, Bank accountWhere your salary is paid, Current
Step 3 of 4, EquipmentOptionalLaptop and accessories
Step 4 of 4, Sign contractElectronic signature

Clickable steps (CRM wizard)

With onValueChange, completed steps become buttons (navigable="completed"). Use "all" or a predicate for free navigation.

Step 4 of 5, Terms, Current
Step 5 of 5, Summary

Step 4 of 5Terms

Editing Terms

States (PRM approval)

Per-step status overrides the derived one: error, skipped (with optional). loading shows a spinner on the current step.

Step 1 of 5, SubmittedNov 2 by Selin Arslan, Completed
Step 2 of 5, Legal reviewClause 7.2 needs changes, Needs attention
Step 3 of 5, FinanceOptional, Skipped
Step 4 of 5, Partner signatureWaiting for DocuSign, Current
Step 5 of 5, Active

Step 4 of 5Partner signature

Variants (checkout)

dots, bar and compact ("Step 3 of 4 · Payment" + bar). Horizontal steppers switch to compact below 640px unless responsive={false}.

Step 1 of 4, Cart, Completed
Step 2 of 4, Shipping, Completed
Step 3 of 4, Payment, Current
Step 4 of 4, Confirmation

Step 1 of 4, Cart, Completed
Step 2 of 4, Shipping, Completed
Step 3 of 4, Payment, Current
Step 4 of 4, Confirmation

API

Stepper

Prop	Type	Default
`value` Required. Current step, 0-based.	`number`	`—`
`onValueChange` Makes navigable steps clickable.	`(index: number) => void`	`—`
`navigable` Which steps may be clicked.	`"completed" \| "all" \| (index) => boolean`	`"completed"`
`orientation` Vertical shows step content under the current step.	`"horizontal" \| "vertical"`	`"horizontal"`
`variant` Indicator style (bar is horizontal only).	`"numbered" \| "dots" \| "bar" \| "compact"`	`"numbered"`
`size` Indicator and text size.	`"sm" \| "md"`	`"md"`
`steps` Data-driven steps. Or pass <Step> children.	`StepItem[]`	`—`
`loading` Spinner in the current step's indicator.	`boolean`	`false`
`responsive` Horizontal steppers show as compact below 640px.	`boolean`	`true`
`aria-label` Name of the ordered list.	`string`	`"Progress"`
`labels` Overrides: label, step ("Step {current} of {total}"), optional, complete, current, error, skipped.	`Partial<StepperLabels>`	`—`

Step / StepItem

Prop	Type	Default
`title` Required. Step name.	`ReactNode`	`—`
`description` Secondary line.	`ReactNode`	`—`
`status` Overrides the status derived from value.	`"upcoming" \| "current" \| "complete" \| "error" \| "skipped"`	`—`
`optional` Shows "Optional" under the title.	`boolean`	`false`
`icon` Replaces the number for upcoming / current steps.	`ReactNode`	`—`
`disabled` Never clickable.	`boolean`	`false`
`children / content` Vertical only: content shown while the step is current.	`ReactNode`	`—`

StepIndicator

Prop	Type	Default
`status` Required. Drives the look.	`StepStatus`	`—`
`number · icon · loading · size` Content of the decorative circle (aria-hidden).	`—`	`—`

Status picker

Process / steps