Stepper

Work in Progress

The refactored stepper is currently missing some advanced features (like editable steps control or bottom label positioning). These are planned for future updates.

Installation

The Stepper component is part of the @repo/ui package.

# This is an internal component
import { Stepper, Step } from "@repo/ui/components";

Usage

The Stepper component handles the navigation header automatically in horizontal mode and provides an accordion-like experience in vertical mode.

import { Stepper, Step } from "@repo/ui/components";

export default function App() {
  return (
    <Stepper orientation="horizontal">
      <Step label="Step 1">Content 1</Step>
      <Step label="Step 2">Content 2</Step>
    </Stepper>
  );
}

Examples

Interactive Configurator

Play with different props to see how the stepper adapts in real-time.

Vertical Layout

Linear Mode

User details and preferences go here.

Orientation

The stepper supports both horizontal and vertical orientations.

Content for step 1.

Linear Mode

Enforce sequential progression. Users can only move forward if the current step is completed.

You must complete this step to proceed.

Mark complete

Optional Steps

Steps can be marked as optional. This is useful for gathering non-essential information.

This step is required.

Error States

Indicate validation issues on specific steps using the hasError prop.

Toggle Error State

Username is already taken!

Custom Icons

Replace default step numbers with custom icons (e.g., Lucide icons).

Home Step

Form Integration

A complex checkout example using react-hook-form and zod for validation.

API Reference

Stepper Props

Name	Type	Default	Description
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction of the stepper.
`linear`	`boolean`	`false`	If true, requires steps to be completed in order.
`defaultStep`	`number`	`0`	Initial active step index (uncontrolled mode).
`step`	`number`	`-`	Active step index (controlled mode).
`onStepChange`	`(step: number) => void`	`-`	Callback when step changes.

Step Props

Name	Type	Default	Description
`label`	`string`	`-`	Title displayed in the step header.
`description`	`string`	`-`	Subtitle displayed below the label.
`icon`	`ReactNode`	`-`	Custom icon for the step indicator.
`optional`	`boolean`	`false`	Marks the step as optional.
`optionalLabel`	`string`	`-`	Text to show when optional (e.g., 'Optional').
`completed`	`boolean`	`false`	Force the step to be marked as completed.
`hasError`	`boolean`	`false`	Show error state only for this step.
`disabled`	`boolean`	`false`	Disable interactions with this step.

useStepper Hook

Allows access to the stepper state from any child component.

Property	Type	Description
`activeStep`	`number`	Current active step index (0-based).
`totalSteps`	`number`	Total number of steps.
`orientation`	`"horizontal" \| "vertical"`	Current orientation layout.
`nextStep`	`() => void`	Function to proceed to the next step.
`prevStep`	`() => void`	Function to go back to the previous step.
`setActiveStep`	`(index: number) => void`	Manually set the active step index.
`reset`	`() => void`	Reset stepper to the first step.

Stepper

On this page