ComponentsNavigationStepper

Stepper

10 variants · horizontal · vertical · icon · timeline · checklist · progress bar · error state

DefaultVerticalPillDotBadgeGradientIconCardProgress barTimelineChecklistError state

Overview

Stepper helps users complete multi-stage workflows with visible progress.

Workflow progress

Live preview

Show completed, current, and upcoming stages in a predictable sequence.

Account setupStep 1
Email verifiedStep 2
Profile detailsStep 3
Payment methodStep 4
ConfirmationStep 5
OnboardingStepper.tsx
tsx
import { Stepper, type StepItem } from 'omverse-ui'
 
const steps: StepItem[] = [
{ label: 'Account setup', sublabel: 'Step 1', description: 'Create your account.' },
{ label: 'Email verified', sublabel: 'Step 2', description: 'Verify your email.' },
{ label: 'Profile details', sublabel: 'Step 3', description: 'Fill in your profile.'},
{ label: 'Payment method', sublabel: 'Step 4', description: 'Add payment method.' },
{ label: 'Confirmation', sublabel: 'Step 5', description: 'Review and confirm.' },
]
 
<Stepper steps={steps} activeStep={step} />

Use a stepper when users complete a linear, multi-stage workflow. Step labels should describe goals rather than interface actions.

Anatomy

  • Step indicators and connectors.
  • Labels and optional sublabels.
  • Icons and status markers where needed.
  • Optional action and optional/description content.

When to use

  • Use when a task requires multiple sequential stages.
  • Use when progress and completion state need to be explicit.
  • Use in onboarding, checkouts, and setup flows.

When not to use

  • Do not use for unrelated or linear actions.
  • Do not force strict steps where branching is required.
  • Prefer tabs when jumps are frequent and random access is important.

Variants

Use variants based on your UI density and whether progress is numeric, icon, or timeline-oriented.

States

  • pending, done, active, and error states should be clearly differentiated.
  • Error states should provide clear remediation guidance.

Behavior

Keep step progress stable, avoid layout jumps, and preserve keyboard focus when navigating steps.

Accessibility

  • Preserve logical reading order and semantic labeling.
  • Use explicit text for status and completion.

Content guidelines

  • Use short labels and avoid long sentence fragments in step headers.
  • Keep descriptions helpful and skimmable.
  • Use optional indicators only when truly optional.

Examples

Default — horizontal

Live preview

Numbered circles with label and sublabel.

Account setupStep 1
Email verifiedStep 2
Profile detailsStep 3
Payment methodStep 4
ConfirmationStep 5
Step 3 / 5
App.tsx
tsx
import { Stepper, type StepItem } from 'omverse-ui'
 
const steps: StepItem[] = [
{ label: 'Account setup', sublabel: 'Step 1', description: 'Create your account.' },
{ label: 'Email verified', sublabel: 'Step 2', description: 'Verify your email.' },
{ label: 'Profile details', sublabel: 'Step 3', description: 'Fill in your profile.'},
{ label: 'Payment method', sublabel: 'Step 4', description: 'Add payment method.' },
{ label: 'Confirmation', sublabel: 'Step 5', description: 'Review and confirm.' },
]
 
<Stepper steps={steps} activeStep={step} />

Default — vertical

Live preview

Vertical orientation with connecting line between steps

Account setupStep 1

Create your account and choose a username.

Email verifiedStep 2

Verify your email address to continue.

Profile detailsStep 3

Fill in your profile information.

Step 3 / 3
App.tsx
tsx
<Stepper steps={steps.slice(0, 3)} activeStep={step} orientation="vertical" />

Pill

Live preview

Pill-shaped step indicators

Step 3 / 5
App.tsx
tsx
<Stepper steps={steps} activeStep={step} variant="pill" />

Dot

Live preview

Minimal dot indicators

Account setup
Email verified
Profile details
Payment method
Confirmation
Step 3 / 5
App.tsx
tsx
<Stepper steps={steps} activeStep={step} variant="dot" />

Badge

Live preview

Numbered badge indicators with label

Account setupStep 1
Email verifiedStep 2
Profile detailsStep 3
Payment methodStep 4
Step 3 / 4
App.tsx
tsx
<Stepper steps={steps.slice(0, 4)} activeStep={step} variant="badge" />

Gradient

Live preview

Gradient fill on active and completed steps

Account setup
Email verified
Profile details
Payment method
Step 3 / 4
App.tsx
tsx
<Stepper steps={steps.slice(0, 4)} activeStep={step} variant="gradient" />

Icon

Live preview

Custom icon inside each step indicator

Sign up
Verify
Customize
Launch
Step 3 / 4
App.tsx
tsx
const iconSteps: StepItem[] = [
{ label: 'Sign up', icon: 'users' },
{ label: 'Verify', icon: 'mail' },
{ label: 'Customize', icon: 'settings' },
{ label: 'Launch', icon: 'rocket' },
]
 
<Stepper steps={iconSteps} activeStep={step} variant="icon" />

Card

Live preview

Each step rendered as a bordered card

Step 3 / 4
App.tsx
tsx
<Stepper steps={steps.slice(0, 4)} activeStep={step} variant="card" />

Progress bar

Live preview

showProgressBar renders a bar below indicators

Account setup
Email verified
Profile details
Payment method
Confirmation
Step 3 / 5
App.tsx
tsx
<Stepper steps={steps} activeStep={step} variant="progress" showProgressBar />

Timeline — vertical

Live preview

Rich vertical timeline with dates and content inside each step

Project kickoffDone
Design phaseDone
DevelopmentCurrent

Core features implemented and integrated with the backend API.

Step 3 / 3
App.tsx
tsx
const timelineSteps: StepItem[] = [
{ label: 'Project kickoff', sublabel: 'Jan 10, 2025', content: <p>Initial meeting. Scope and milestones defined.</p> },
{ label: 'Design phase', sublabel: 'Feb 3, 2025', content: <p>Wireframes and prototypes approved.</p> },
{ label: 'Development', sublabel: 'Mar 15, 2025', content: <p>Core features implemented.</p> },
]
 
<Stepper steps={timelineSteps} activeStep={step} variant="timeline" orientation="vertical" />

Checklist style

Live preview

Task-list style vertical stepper — supports optional steps

Step 3 / 5
App.tsx
tsx
const checklistSteps: StepItem[] = [
{ label: 'Install dependencies' },
{ label: 'Configure environment' },
{ label: 'Set up database' },
{ label: 'Run migrations', optional: true },
{ label: 'Deploy to production' },
]
 
<Stepper steps={checklistSteps} activeStep={step} variant="checklist" orientation="vertical" />

With error state

Live preview

Use explicit status props to show complete, error, and pending states

Account
Verify
Profile
Payment
App.tsx
tsx
const steps: StepItem[] = [
{ label: 'Account', status: 'done' },
{ label: 'Verify', status: 'error' },
{ label: 'Profile', status: 'pending' },
{ label: 'Payment', status: 'pending' },
]
 
<Stepper steps={steps} currentStep={1} />

Props / API

Stepper props

Props

PropTypeDefaultDescription
stepsStepItem[][]Array of step definitions
activeStepnumber0Index of the currently active step (0-based)
variant'default' | 'pill' | 'dot' | 'badge' | 'gradient' | 'icon' | 'card' | 'progress' | 'timeline' | 'checklist''default'Visual style of the stepper
orientation'horizontal' | 'vertical''horizontal'Direction of the stepper
color'default' | 'success' | 'secondary''default'Color scheme for active/completed steps
clickablebooleanfalseAllow clicking completed steps to go back
currentStepnumber0Alias for active step where supported by legacy variants

StepItem shape

Props

PropTypeDefaultDescription
idstring—Unique identifier for the step (required)
labelstring—Step label shown below/beside the indicator
sublabelstring—Smaller secondary label
descriptionstring—Longer description text
iconIconName—Icon name for the step indicator (icon variant)
status'done' | 'active' | 'error' | 'pending'—Explicit step status override
optionalbooleanfalseShows an optional badge on the step
contentReactNode—Content shown inside the step (timeline variant)