Stepperize v9Explore the changes
Skip to Content
Stepperize

Steps and ids

Model each step with a stable id, and keep your own data on it.

A step is a plain object. Only id is required; everything else belongs to your app.

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

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

The definition is the contract for the whole flow. The hook, match, the data of each step, the next map and the primitives all use these same ids, and TypeScript knows them as the union "shipping" | "payment" | "review".

Step ids

Ids are what you save, put in the URL and branch on. Pick ones that describe the business step, not the current label or position.

GoodAvoidWhy
"shipping""Step 1"Reordering steps would change its meaning.
"payment""Pay now"Copy changes; ids should not.
"review""confirm-2026"Generated ids cannot be typed or bookmarked.

Ids must be unique. An empty list or a repeated id throws SZ103 when the definition is created.

Your own fields

Any other field stays on the step, fully typed, wherever Stepperize hands you a step: stepper.current, stepper.steps, the match handlers and the Stepper.List function.

function Header() {
  const stepper = checkout.useStepperContext();
  return (
    <h2>
      <Icon name={stepper.current.icon} /> {stepper.current.title}
    </h2>
  );
}

Two fields have a meaning for the library:

FieldUsed for
schemaTypes the step's data, and next() validates against it. See Validation.
title, descriptionShown by Stepper.Title and Stepper.Description. A string title is also what screen readers hear when the step changes.

Everything else (icon, optional, estimatedMinutes, a component) is yours.

Define once, at module scope

A definition holds no state. It is the description of the flow, plus the hooks and components bound to it. Create it once, outside your components, and import it where you need it.

// Wrong: a new definition, and a new empty flow, on every render.
function Checkout() {
  const checkout = defineStepper([{ id: "shipping" }, { id: "payment" }]);
  const stepper = checkout.useStepper();
}

Every useStepper() call or Provider of the same definition is an independent flow, so one definition can back several flows on a page.

Keep ids literal

Ids stay literal when the array is written inline. If you build the array first, add as const, or the ids widen to string and you lose the checks.

// Ids are string: nothing is checked.
const steps = [{ id: "account" }, { id: "profile" }];
const loose = defineStepper(steps);

// Ids are "account" | "profile".
const inline = defineStepper([{ id: "account" }, { id: "profile" }]);

const list = [{ id: "account" }, { id: "profile" }] as const;
const pinned = defineStepper(list);

Fields that only some steps have

stepper.current is the union of all your steps. A field that exists on some steps only is not available until you know which step you are on. match narrows for you:

const signup = defineStepper([
  { id: "account", title: "Account", help: "We never share your email." },
  { id: "done", title: "All set" },
]);

function Body() {
  const stepper = signup.useStepperContext();
  return stepper.match({
    account: (step) => <p>{step.help}</p>,
    done: (step) => <p>{step.title}</p>,
  });
}

Comparing stepper.current.id narrows it too.

Next: the flow and the stepper, the objects you work with at runtime.

Edit on GitHub

Last updated on

On this page