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.
| Good | Avoid | Why |
|---|---|---|
"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:
| Field | Used for |
|---|---|
schema | Types the step's data, and next() validates against it. See Validation. |
title, description | Shown 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.
Last updated on