Progress Stepper

v1.0.0

Ready for Production

Catalyst Progress Stepper is a context-driven compound component with orb, linear, and segmented progress variants for guiding users through sequential workflows. It ships a useStepperNavigation hook for Continue / Back controls, and meets WCAG 2.2 AA out of the box.

Installation

npm install @pmi/catalyst-stepper

import {
  StepperRoot,
  StepperList,
  StepperStep,
  StepperLine,
  StepperOrb,
  useStepperNavigation,
} from '@pmi/catalyst-stepper';

Variants

Full Orbs

Numbered orb indicators that display a check icon when complete. Best for 3–6 steps where each step has equal visual weight.

Linear

A single continuous progress bar that fills as steps complete. Ideal for many steps or when individual step identity is less important.

Segmented

Discrete equal-width segments — one per step — that fill independently. Good for checkout-style flows with 3–6 steps of equal weight.

Minimal Orbs

Compact 16 px orbs (size="sm") for space-constrained layouts such as modals or sidebars.

Common Patterns

Full Orbs with Progress Counter

Adds a progress counter header (Application progress — 1/5) above the orbs.

Full Orbs with Segment Labels

Displays a text label beneath each orb. Use when step names add meaningful context.

Minimal Orbs with Progress Counter

Compact orbs combined with the progress counter header.

Linear with Progress Counter

Linear progress bar paired with the progress counter header.

Segmented with Progress Counter

Segmented progress stepper paired with the progress counter header.

Full Orbs with Labels and Content Panel

Orbs with segment labels and a content panel per step.

Clickable Steps

Each orb is an interactive button that navigates directly to that step. Use the asChild prop on StepperStep to merge aria-current and the accessible label onto any child element — no separate Continue/Back navigation needed.

API Reference

Progress Stepper is a compound component. The sections below document the Catalyst-specific props for each primitive.

StepperRoot

The root container that manages active-step state and distributes it to child components via React Context. Supports both controlled (value + onValueChange) and uncontrolled (defaultValue) usage. Set variant here once to apply it to StepperList and StepperLine automatically.

StepperList

Flex row or column container for step indicators. When navProps is provided, wraps the <ol> in a <nav> landmark.

StepperStep

A single step item rendered as an <li>. Automatically derives its status from StepperRoot context when stepValue is provided. For interactive steps, use the asChild prop to merge aria-current onto a child <a> or <button>.

StepperLine

Connector element rendered between step orbs, or used as the progress bar for linear and segmented variants. Variant is inherited from StepperRoot context.

StepperOrb

Circular indicator showing pending (number), current (highlighted), or complete (check icon) state.

Accessibility

Progress Stepper is designed to meet WCAG 2.2 AA standards.

Keyboard Interactions

ARIA

• StepperList renders an <ol> inside a <nav aria-label="..."> landmark when navLabel is provided. The <ol> carries role="list" to preserve list semantics in VoiceOver when list-style: none is applied.
• Each StepperStep renders an <li role="listitem"> with aria-current="step" on the active step. For non-interactive steps a visually hidden <span> inside the <li> carries the full accessible label generated by buildStepAriaLabel (e.g. "Step 2 of 5: Shipping Info, Completed"). For interactive steps (asChild), the span is omitted, aria-current moves to the child interactive element, and the same label is applied as aria-label on that element — ensuring the name is announced exactly once.
• StepperOrb and its children are fully aria-hidden — all status information is conveyed by the sr-only label or button aria-label in StepperStep.
• StepperLine decorative connectors are aria-hidden="true".
• In the linear and segmented variants, the progress bar (StepperList aria-hidden) is hidden from AT. An aria-live="polite" sr-only region announces step changes after the first user interaction.

Choosing the Right Component

Use Progress Stepper when you need to guide users through a linear sequence of discrete steps with clear progress indication. Reach for a different primitive when:

Related

• Tabs
• Progress Bar
• Button