Stepper

A production-grade, highly animated multi-step wizard component built on plain CSS transitions and the Web Animations API — no animation library. It splits the layout into two decoupled blocks: the visual progress tracker and the bidirectional sliding content payload.

Unlike basic UI placeholders, this engine is designed to handle real form state, per-step input validation, and asynchronous API submission handling (including error states) with silky 60fps transitions.

Stepper (the tracker) and StepperContent (the sliding payload) are decoupled — they only share the steps array and a currentStep number that you own, so Stepper also works alone as a progress header above content you lay out yourself. Validation, submission and error handling stay in your component.

Stepper

Per-step validation blocks Next, and the Review step can simulate a failed submit.

Passsteps: as { id, title }[] — description, icon and content are optional per step.
currentStep: is the zero-indexed active step, and drives the progress line fill.
onStepChange: makes the circles clickable. Omit it and they become static indicators.
color: takes any CSS colour — hex, rgb(), oklch(), var(--token) — applied inline. A Tailwind class works for the line and circles, but the pulse ring is skipped, since its border colour would need a class Tailwind's scanner never sees.

Accent Color

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Install Stepper

npx shadcn@latest add @algorize-ui/stepper

components/custom/blocks/StepperBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Step 1 installs this for you. Run it yourself only if you are adding Stepper to an existing project by hand. The cn helper and lucide-react are not listed — the installation guide covers them once for every component.

select is a component, not a package — the shadcn CLI installs it as source files.

npx shadcn@latest add @algorize-ui/select

Features

Learn about the Stepper component's linear progression features, providing clear visual feedback for multi-step forms and processes.

Customizable

Easily adapt the component's styling and behavior to fit your application's unique design system.

Accessible

Built with accessibility in mind, ensuring all users can interact with your application effectively.

Responsive

Fully responsive design that looks and works great across desktop, tablet, and mobile devices.

Performant

Optimized for maximum performance with minimal re-renders and efficient state management.

Best Practices & Guidelines

Usage Guidelines

Follow standard design principles when implementing this component. Ensure proper contrast, spacing, and context within your layout.

Props Reference

Stepper

The visual navigation header component that renders step indicators and the animated progress fill line.

Prop	Type	Default	Description
`steps`	`Step[]`	Required	An array of step objects defining the sequence. Each object requires an `id` and `title`. `description`, `icon`, and `content` are optional.
`currentStep`	`number`	Required	The active zero-indexed step of the sequence. Controls the progress line fill and active/completed indicator states.
`onStepChange`	`(step: number) => void`	`undefined`	Callback fired when a user clicks directly on a step circle in the header. If omitted, the steps become static visual indicators.
`color`	`string`	`"var(--primary)"`	The active theme color for the progress line, active/completed circles and pulse ring. Supports any CSS color value or Tailwind background class.
`className`	`string`	`undefined`	Custom Tailwind CSS classes to apply to the outermost navigation header wrapper.

StepperContent

The sliding content container component that handles the animated sliding entrance of each step payload.

Prop	Type	Default	Description
`steps`	`Step[]`	Required	The identical array passed to the header component. Renders the active step's `content` node.
`currentStep`	`number`	Required	The active zero-indexed step used to identify which payload to render and determine the sliding transition direction.
`className`	`string`	`undefined`	Custom Tailwind CSS classes applied to the sliding content wrapper container.

Step (TypeScript Interface)

The TypeScript interface defining the structure of each object in the steps array prop.

Property	Type	Required	Description
`id`	`string`	Yes	A unique identifier string required for safe React list rendering.
`title`	`string`	Yes	Primary headline text displayed prominently below the step circle indicator.
`description`	`string`	No	Optional secondary helper text displayed directly underneath the step title on larger screens.
`icon`	`React.ElementType`	No	Optional Lucide React icon or custom SVG component rendered inside the step circle indicator instead of a default number.
`content`	`React.ReactNode`	No	The JSX/UI payload (e.g., input forms, review summaries) rendered inside `StepperContent` when this step is active.