Installation

Most React apps only install the React package. It includes the React API and depends on the core package for the shared types and pure helpers.

Install the React package with your package manager:

pnpm add @stepperize/react

First import

Create the stepper definition near the feature that owns the flow. A definition is not React state; it is the typed description of the flow.

import { defineStepper } from "@stepperize/react";

const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);

Only id is required. Everything else is your data and stays typed.

Using your own UI

Choose the optional lightweight entry if you do not need generated Stepper components:

import { defineStepper } from "@stepperize/react/headless";

It comes with the same package and retains hooks, Provider, selectors and validation. Its definition has no Stepper property. Use the main entry for the accessible UI primitives. See bundle measurements and a complete example.

TypeScript setup

Stepperize works best when TypeScript can keep your ids literal.

const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);

With the inline array above, TypeScript understands that valid ids are "shipping" | "payment" | "review". That is why stepper.goTo("paymant") becomes a type error instead of a runtime surprise.

Packages

Most apps only need @stepperize/react.

Requirements

Stepperize supports React 18 and 19. It can run in JavaScript too, but you lose most of the type-safety that makes the library useful.

Next: build your first stepper.