Stepper
Progress and optional backward navigation through a multi-step task.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from @commenda/pathfinder/stepper. Interactive callbacks belong in a client component in Next.js App Router.
API reference
| Prop | Type | Behavior |
|---|---|---|
labelRequired | string | Required; ordered-list name |
itemsRequired | readonly StepperItem[] | Required; id, label, state, optional description |
orientation | "vertical"|"horizontal" | horizontal |
navigationConfig | ObjectView fields | Optional; only done steps request navigation |
stateLabels | Partial<Record<"done" | "disabled" | "upcoming" | "current", string>> | Localized Upcoming, Current step, Completed, Unavailable |
id | string | Stable HTML identifier for the component. |
className | string | Additional classes for the component root. |
Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Item IDs/values must be unique and stable.
Usage rules
Each step explicitly declares state: upcoming | current | done | disabled. At most one is current; a finished flow can have none. The component does not duplicate that state with a separate current index.
Done steps become native buttons when navigationConfig is supplied. Upcoming and disabled steps do not navigate. The application owns validation, retained answers, Back/Continue/Submit actions, and focus after navigation. A failed field remains a field error; it does not create a red step marker. Keep later completed steps done when revisiting earlier answers unless those answers invalidate them.
Prefer three to six steps on a full page. Use the vertical layout when a narrow container cannot fit clear horizontal labels. The page owns sticky positioning. The Navigation example illustrates navigation only, not a production validation engine.
Examples
Vertical
Navigation
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Stepper
Source: 676:104, items 676:61, behavior 676:35169, guidance 676:35190.
STEPPER-01— Source/Pathfinder: explicit upcoming/current/done/disabled states, at most one current. Only done steps with navigationConfig become buttons; callbacks request navigation without changing caller-owned state. Current exposes aria-current=step.STEPPER-02— Source: current-step validation, saved answers, footer buttons, and focus belong to the application. Field errors never invent a red marker. Final primary action says Publish, Submit, or Create. Keep completed steps when revisiting unless the application invalidates them.STEPPER-03— Source: three to six steps on full pages. Short labels, optional descriptions. Parent owns sticky positioning and responsive choice of horizontal/vertical layout.STEPPER-04— Source: 20 markers, upcoming pearl-300/900, current blue-700/white, done green-700/check, disabled pearl-100/600. Horizontal text gap 8, connector at marker center with 12 side gaps. Vertical 240, padding 8, gap 12, row gap 2, radius 8. Weight never shifts; completion enters without bounce and never animates on initial mount.