Stepperize Documentation

Stepperize is a library for building typed multi-step flows in React. It allows you to define a sequence of named steps once, and then uses that single definition to drive hooks, providers, and UI primitives. This ensures that your step IDs, titles, and rendering logic remain synchronized and type-safe throughout your application.

Common use cases include:

• Checkout flows
• Onboarding processes
• Account setup
• Surveys
• Import wizards
• Approval flows
• Multi-step forms

The project is organized into several packages:

• @stepperize/core: Framework-agnostic utilities and TypeScript types for step-based workflows.
• @stepperize/react: React and React Native bindings, including defineStepper and unstyled primitives.
• docs: The Stepperize documentation site, block gallery, changelog, and shadcn-compatible registry.

Navigation methods like next, prev, goTo, and reset are asynchronous because they may trigger beforeStepChange guards. These methods return a Promise, which is always truthy. If you need to check if the navigation was actually accepted (e.g., a validation guard returned false), you must await the call.

// ❌ `accepted` is a Promise, so this branch never runs
const accepted = stepper.next();
if (!accepted) return;

// ✅ await to read the boolean result
const accepted = await stepper.next();
if (!accepted) return;

Stepperize distinguishes between positional status and business-logic completion:

• stepper.status(id): Returns the positional state based on the current index. Possible values are "active", "previous", or "upcoming".
• stepper.isComplete(id): Represents explicit business state. A step is not considered complete just because the user passed it; you must explicitly set it using setComplete(id) or setComplete(id, false).

Any properties you add to a step object (besides the required id) are available throughout the stepper instance. This is useful for rendering headers, icons, or handling per-step validation schemas.

Commonly used custom fields:

• title / description: For UI labels and headers.
• schema: For per-step validation logic.
• optional: For UI labels and completion rules.
• icon: For stepper indicators.

You can access these via the stepper.current object in your components.

function Header() {
  const stepper = checkout.useStepper();

  return (
    <header>
      <h2>{stepper.current.title}</h2>
      <p>{stepper.current.description}</p>
    </header>
  );
}

The linear option (a boolean) controls trigger affordances like pointer and keyboard navigation. It does not restrict imperative navigation via stepper.goTo(id), which always bypasses the policy.

• linear: false (default): canGoTo allows any known step; all triggers are enabled.
• linear: true: canGoTo only allows previous steps, the current step, and the immediate next one. Primitive triggers and list keyboard navigation follow this constraint.

Use stepper.canGoTo(id) to determine if a specific jump button or step trigger should be enabled in the UI.

const checkout = defineStepper(steps, {
  linear: true,
});

// In your UI:
<button
  type="button"
  disabled={!stepper.canGoTo("review")}
  onClick={() => stepper.goTo("review")}
>
  Review
</button>

Stepperize is designed to be additive. You can start with simple local state and move to more complex architectures without rewriting your core logic:

1. Local: Use useStepper() within a single component with your own custom markup. This is the starting point for most flows.
2. Guarded: Implement beforeStepChange to handle validation or data saving before a user moves to the next step.
3. Drafts: Use the data property when steps require per-step data for persistence or review.
4. Shared: Use a Provider when your stepper UI is split across separate components (e.g., a header, a main panel, and a footer).
5. Primitives: Use the built-in Stepper.* components for a fully accessible and styled stepper UI.

To ensure maximum type safety, define your stepper using an inline array within defineStepper. This allows TypeScript to treat the id values as literal types (e.g., "shipping" | "payment" | "review"). This prevents runtime errors by causing TypeScript to throw an error if you attempt to navigate to an invalid ID, such as stepper.goTo("paymant").

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

When integrating React Hook Form with Stepperize, use the following mapping for core patterns: