Stepper

A progress indicator for multi-step flows. Renders a list of steps against a current index, deriving three states per step — complete, active, and upcoming. Use orientation="horizontal" (default) for numbered wizards with connectors, or orientation="vertical" for a timeline.

Import

import { Stepper } from "@roger-emerson/ploxum-primitives";

Usage

const phases = [
  { id: "load-in", title: "Load-in", description: "Crew + gear staged" },
  { id: "doors", title: "Doors", description: "Guests entering" },
  { id: "go-live", title: "Go Live", description: "Show running" },
  { id: "load-out", title: "Load-out", description: "Teardown + strike" },
];
 
function EventProgress() {
  const [current, setCurrent] = useState(1);
  return <Stepper current={current} onStepChange={setCurrent} steps={phases} />;
}

For a timeline, pass orientation="vertical" and an optional per-step icon:

<Stepper
  current={2}
  orientation="vertical"
  steps={[
    { id: "confirmed", title: "Order confirmed", icon: <Check /> },
    { id: "dispatched", title: "Crew dispatched", icon: <Truck /> },
  ]}
/>

Props

Prop	Type	Default	Description
`steps`	`StepperStep[]`	—	Steps to render. Each has `id`, `title`, optional `description` and `icon`.
`current`	`number`	—	Controlled active step index. When set, the component is controlled.
`defaultCurrent`	`number`	`0`	Initial active step index for uncontrolled use.
`onStepChange`	`(index: number) => void`	—	Fired when a step is clicked.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Row of circles with connectors, or a vertical timeline.
`className`	`string`	—	Merged onto the root element.

StepperStep

Field	Type	Description
`id`	`string \| number`	Stable key.
`title`	`string`	Step label.
`description`	`string`	Optional supporting text.
`icon`	`ReactNode`	Optional glyph rendered inside the circle in place of the number.

States

complete (index < current) — filled amber circle with a Check icon (or the step's icon). Preceding connectors fill amber.
active (index === current) — filled amber circle showing the step number (or icon) with a subtle ring.
upcoming (index > current) — muted circle with the step number.

Design rules

Text on the amber fill uses --ploxum-color-text-inverse; connector tracks use --ploxum-color-border-subtle and fill with --ploxum-color-amber-default.
Steps are clickable and call onStepChange(index) — wire navigation through it, or treat it as read-only by omitting the handler.
Motion uses ploxum springs (firm for connectors, snappy for circles) with a staggered listItem entrance. Under prefers-reduced-motion springs and per-item delays are dropped — fills and entrances resolve instantly.

Storybook

Open Stepper in Storybook ↗