Stepper

A multi-step progress indicator with horizontal and vertical orientations. Auto-derives step status from activeStep with accessible ARIA roles — copy it into your project and own it completely.

Horizontal (Default)

Account

Profile

Review

With Descriptions

Account

Create your account

Profile

Set up your profile

Review

Confirm details

Vertical

Account

Profile

Review

All Steps Complete

Account

Profile

Review

Installation

npx visor add stepper

This copies two files into your project:

components/ui/stepper/stepper.tsx — the component
components/ui/stepper/stepper.module.css — the styles

Usage

import {
  Stepper,
  StepperItem,
  StepperTrigger,
  StepperTitle,
  StepperSeparator,
} from '@/components/ui/stepper/stepper';

export default function Example() {
  return (
    <Stepper activeStep={1}>
      <StepperItem step={0}>
        <StepperTrigger step={0} />
        <StepperTitle>Account</StepperTitle>
      </StepperItem>
      <StepperSeparator complete />
      <StepperItem step={1}>
        <StepperTrigger step={1} />
        <StepperTitle>Profile</StepperTitle>
      </StepperItem>
      <StepperSeparator />
      <StepperItem step={2}>
        <StepperTrigger step={2} />
        <StepperTitle>Review</StepperTitle>
      </StepperItem>
    </Stepper>
  );
}

API Reference

StepperProps

Prop	Type	Default	Description
`activeStep`	`number`	`0`	Zero-based index of the currently active step. All steps before this index are considered complete.
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Layout direction of the stepper. "vertical" stacks steps top-to-bottom.
`step`*	`number`	—	Zero-based step index passed to StepperItem and StepperTrigger. Used to auto-derive status.
`status`	`'complete' \| 'active' \| 'upcoming'`	—	Explicit status override for StepperItem or StepperTrigger. Auto-derived from activeStep if omitted.
`complete`	`boolean`	`false`	Whether the StepperSeparator line renders in its completed style.
`className`	`string`	—	Additional CSS class names to merge onto the element.

Sub-components

Component	Element	Purpose
`Stepper`	`<div>`	Root container with context provider
`StepperItem`	`<div>`	Step wrapper, auto-derives status from `activeStep`
`StepperTrigger`	`<button>`	Clickable step indicator circle
`StepperTitle`	`<div>`	Step label
`StepperDescription`	`<p>`	Step description
`StepperSeparator`	`<div>`	Connecting line between steps

Accessibility

Stepper renders with role="group" and aria-label="Progress" to group the steps as a meaningful unit.
StepperItem sets aria-current="step" on the currently active step.
StepperTrigger is a <button> element and includes a visually hidden label ("Completed" or "Step N") for screen readers.
The check icon in completed triggers has aria-hidden="true" since the status is communicated via the button's text content.
Step status (complete, active, upcoming) is also exposed as a data-status attribute for custom CSS targeting.
When steps are clickable (navigating back), ensure StepperTrigger has a meaningful onClick handler. For read-only steppers, pass disabled or tabIndex={-1} to prevent interaction.

Stepper

On this page