React Stepper Component Examples

The canonical Stepper use is a checkout indicator with four named stages — cart, shipping, payment, review — sitting above the form that swaps based on the active step. Hold the step in React.useState, pass it as the step prop, and pass setStep as onStepChange so the user can jump back to a completed stage by clicking its indicator. Each Stepper.Item takes a label prop, which widens the indicator with px-3 and renders the text in place of the auto-number.

Drop this above a Tabs panel or a conditional render that swaps a CartForm, ShippingForm, PaymentForm, and ReviewSummary based on step. The completed states light up automatically as the user advances — every indicator below step gets a green Check icon, the active indicator gets the primary ring, and upcoming indicators stay muted. Pair the stepper with a row of Button Next / Back controls under the form.

For an onboarding flow where the stages are best telegraphed by an icon rather than a label — a user silhouette for the account step, a document for the profile step, an envelope for the verification step — pass an icon prop on each Stepper.Item instead of a label. The component renders the icon at size-4 inside the round indicator, and the auto-numbering falls away. Once a step is completed the Check icon takes over regardless of the original icon, so the visual treatment of "this stage is done" stays consistent across the row.

Use lucide-react icons (the same set the rest of the Drivn registry pulls from) to keep the bundle lean. The icon prop type is React.ComponentType<{ className?: string }> — pass the component reference (icon={User}), not a JSX element. Wrap the whole stepper inside a Card header and render the matching form below to land the visual hierarchy.

When the flow is tall enough that a horizontal row would crowd the viewport — a settings migration with eight stages, an admin onboarding sequence inside a sidebar, a documentation walkthrough on a marketing page — switch to orientation="vertical". The root flips to flex-col, the indicators stack from top to bottom, and the connector becomes a vertical column (w-0.5 min-h-6 self-center) sized to give each stage breathing room.

The same step, onStepChange, label, and icon props apply. Render the active stage's form to the right of the stepper inside a two-column grid — the stepper holds the structural navigation and the right column owns the inputs. For a stepper used purely as a read-only progress indicator, drop the onStepChange prop and the indicators stay clickable but inert. Pair the layout with a Separator between the stepper and the right-hand panel.

For a slide-deck pager, a multi-step photo carousel indicator, or an onboarding pill row in a marketing hero — situations where the connector line between indicators reads as noise rather than progress — pass line={false} on the parent. The root applies the justify-between class so the items spread across the available width with even spacing, and the connector lines drop out of the render entirely. Each indicator still cycles through the active / completed / upcoming states, still auto-numbers, still fires onStepChange on click.

Drop this on a landing page to indicate "you are on slide 2 of 4" or inside a Dialog header to indicate a short three-step confirmation flow. With no labels and no icons, the indicators render as round numbered pills — 1, 2, 3, 4 — which is the smallest possible visual treatment the Stepper supports.

Pass disabled on a single Stepper.Item and the component applies opacity-50 cursor-not-allowed to that indicator, sets the underlying button's disabled attribute, and silently ignores clicks — onStepChange never fires for that index. The rest of the row stays interactive. Use this to enforce "the user must finish step 2 before jumping to step 4" — track a completed boolean per stage in your wrapper state, derive disabled={!isCompleted} per item, and the indicator becomes a lock that users cannot bypass with a click.

This pairs with form validation. In a controlled wizard, set the next step's disabled flag based on whether the current step's form is valid. The user gets immediate visual feedback that "this step is gated", and the focus management stays inside the active stage until the gate opens. Combine with a Toast notification to explain why the gate is closed.

The Stepper renders the indicator row, but moving between steps via explicit buttons is just as common as click-to-jump — a wizard inside a Dialog or a Card almost always pairs the row with a Next button on the right and a Back button on the left. Hold the step in state, pass setStep as onStepChange (so click-to-jump still works), and wire two Button elements that increment and decrement the index.

Clamp the increment with Math.min(step + 1, steps.length - 1) and the decrement with Math.max(step - 1, 0) so the buttons disable themselves at the ends — or set the disabled prop on the buttons directly. Render the active step's form between the stepper row and the controls. For an asynchronous flow where Next has to wait on a server action, swap the Next button text for a loading spinner while the action is pending.