Stepper

A versatile stepper component built on Radix UI Tabs primitive that guides users through multi-step processes. Features three distinct visual styles (orbs, linear, segmented), optional progress tracking, and full keyboard navigation support.

Installation

Install the Stepper component from the Catalyst component library:

npm install @pmi/catalyst-stepper

Examples

Basic Orb Stepper

A full-sized orb stepper with numbered indicators that show checkmarks on completion:

With Progress Title

Add a title bar showing current progress:

With Step Labels

Display labels below each orb indicator:

Minimal Orb Size

Compact orb indicators (16px) for space-constrained layouts:

Full Orbs With Labels No Content

Stepper with labels but without content panels:

Linear Progress Bar

Continuous linear progress indicator:

Linear with Title

Linear progress bar with progress counter:

Segmented Progress

Discrete segments for each step:

Custom Themed Stepper

Customize colors using Tailwind classes for brand-specific themes:

Vertical Stepper

A vertical layout with orbs on the left, step labels beside each orb, and vertical connector bars between steps. Uses orientation="vertical" on StepperList and StepperLine, and size="md" with labelPosition="right" on StepperOrb. Ideal for sidebar navigation in multi-step forms:

Component API

StepperRoot

The root container component built on Radix UI Tabs.Root.

StepperList

Container for step indicators or navigation buttons.

StepperTrigger

Trigger component for step navigation, typically wrapped in a Button.

StepperContent

Content panel for each step.

StepperLine

Progress line indicator between steps.

StepperOrb

Circular step indicator with status-based styling.

Usage Guidelines

When to Use

• Multi-step Forms: Guide users through complex form workflows
• Onboarding Flows: Welcome new users with sequential setup steps
• Checkout Processes: Show progress through purchase steps
• Wizard Interfaces: Any multi-step process requiring clear progress indication

State Management Pattern

The Stepper requires state management to track the current step:

const [currentStep, setCurrentStep] = useState(0);

const handleValueChange = (value: string) => {
  const index = steps.findIndex((s) => s.value === value);
  if (index >= 0) setCurrentStep(index);
};

Status Calculation

Use the data-status attribute to indicate step state:

• "complete": Steps before current (index < currentStep)
• "current": Active step (index === currentStep)
• "" (empty): Future steps (index > currentStep)

Visual Variants

Orbs: Best for 3-5 steps with clear progression Linear: Ideal for many steps or continuous progress Segmented: Good for discrete steps with equal weight

Accessibility

Keyboard Navigation

• Arrow Keys: Navigate between steps (when activationMode="automatic")
• Tab: Focus navigation buttons
• Enter/Space: Activate buttons to change steps
• Home/End: Jump to first/last step

Screen Reader Support

• Use aria-label on StepperContent to announce position
• Navigation buttons have clear labels ("Continue", "Back", "Submit")
• Progress indicators marked with aria-hidden as they're decorative

Focus Management

• Focus moves to content panel after step change
• Visible focus indicators on interactive elements
• onFocus prevented on StepperTrigger to avoid automatic navigation

Best Practices

Do

✅ Provide clear step content for each stage ✅ Show progress indication (title bar or counter) ✅ Include both forward and back navigation ✅ Use appropriate variant for step count (orbs for few, linear for many) ✅ Validate step completion before allowing progression

Don't

❌ Use too many steps (consider breaking into multiple flows) ❌ Allow skipping required steps without validation ❌ Hide the current step indicator ❌ Use different variants within the same stepper ❌ Forget to show final "Submit" action

Design Tokens

The Stepper uses these design tokens from the Catalyst theme:

• Colors: pmi-off-black, pmi-violet, pmi-neutral, pmi-aqua (custom theming)
• Spacing: Gap utilities, padding for content areas
• Typography: Font display for indicators, base for content
• Borders: Rounded utilities for orbs and lines
• Transitions: Smooth state changes for indicators

Related Components

• Button - Used for navigation controls
• Tabs - Similar tab-based navigation
• Progress - Simpler progress indication
• Icons - CheckIcon for completed steps