defineStepper
Create the typed definition of a flow, and everything it returns.
import { defineStepper } from "@stepperize/react";
const checkout = defineStepper(steps, defaults);Parameters
| Name | Type | Description |
|---|---|---|
steps | Step[] | At least one step, with unique ids. |
defaults | Options | Optional. Options applied to every flow of this definition; each flow can override them. |
A step is an object with an id, an optional schema, and any other field you
want. See Steps and ids.
const checkout = defineStepper(
[
{ id: "shipping", title: "Shipping", schema: shippingSchema },
{ id: "payment", title: "Payment", schema: paymentSchema },
{ id: "review", title: "Review" },
],
{ linear: true },
);An empty list or a duplicate id throws SZ103.
Call it once at module scope, in a client module. It creates a React context, so it cannot run in a Server Component.
Returns
| Property | Description |
|---|---|
steps | The steps you passed, with their literal types. |
useStepper(options?) | Creates a flow owned by the component and returns its stepper. |
Provider | Creates a flow and shares it with the components below. |
useStepperContext(selector?) | Reads the flow of the nearest Provider or Stepper.Root. |
Stepper | The primitives. Not present when importing from /headless. |
create(options?) | Creates a flow without React. |
steps
The array you passed. Use it to render lists and to look steps up; it is plain data.
checkout.steps.map((step) => step.title);
checkout.steps.find((step) => step.id === "payment");useStepper
const stepper = checkout.useStepper(options);Creates a flow that belongs to the component, and returns its stepper. The component re-renders on every change of the flow.
- Every call creates an independent flow, also below a
Providerof the same definition. To read a shared flow, useuseStepperContext. optionsare merged over the definition's defaults. Callbacks may be new functions on every render; the flow always calls the latest ones.snapshotis read once, when the component mounts.- The flow is destroyed when the component unmounts, which cancels a move that is still running.
Provider
<checkout.Provider linear onFinish={placeOrder}>
<Header />
<Steps />
</checkout.Provider>Creates a flow and provides it to every component below. Its props are the
options plus children. It renders no element.
A Provider inside another Provider of the same definition starts a
separate flow for its own subtree.
useStepperContext
const stepper = checkout.useStepperContext();
const title = checkout.useStepperContext((stepper) => stepper.current.title);Reads the flow of the nearest Provider or Stepper.Root of this
definition. Outside one, it throws SZ100.
| Call | Returns | Re-renders |
|---|---|---|
useStepperContext() | The stepper | On every change of the flow |
useStepperContext(selector) | What the selector returns | When that result changes |
The result is compared with Object.is. A selector that returns a string, a
number, a boolean, or an object the stepper already holds (such as
stepper.current or stepper.data.shipping) skips the renders it does not
need. A selector that builds a new object or array is safe, and re-renders on
every change.
const id = checkout.useStepperContext((s) => s.current.id); // only when the step changes
const pending = checkout.useStepperContext((s) => s.isPending); // only when it flips
const shipping = checkout.useStepperContext((s) => s.data.shipping); // only when that step's data changescreate
const flow = checkout.create(options);Creates a flow with no React involved: the same state machine, with the same options and the definition's defaults. Use it in tests, on a server, or anywhere outside a component. See Core.
Without the primitives
import { defineStepper } from "@stepperize/react/headless";The same function, returning the same definition without Stepper. It has no
DOM code, which keeps the primitives out of your bundle and makes it usable in
React Native.
Types
Derive the types of a flow from its definition:
type CheckoutStepper = ReturnType<typeof checkout.useStepper>;
type StepId = (typeof checkout.steps)[number]["id"];
type CheckoutSnapshot = ReturnType<CheckoutStepper["snapshot"]>;Generic helpers are exported from @stepperize/react (and from
@stepperize/core):
| Type | Description |
|---|---|
Step | { id: string; schema?: StandardSchemaV1 } plus your own fields. |
Id<S> | Union of the step ids of a step list. |
Input<S, I>, Output<S, I> | What a step stores, and what its schema produces. |
FlowData<S> | The data of every step, by id. |
Options<S> | The options. |
Stepper<S> | What the hooks return. |
Snapshot<S> | { step, history, data, complete }. |
Result<S>, Reason | What a move resolves with. |
GuardContext<S> | The argument of guard. |
StepState | "pending" | "current" | "complete". |
Issue | { message, path? }, as Standard Schema defines it. |
Definition<S>, ProviderProps<S> | What defineStepper returns, and the props of its Provider. |
RootProps<S>, ListProps<S>, ItemProps<S>, ContentProps<S>, ItemValue<S> | Props of the primitives, and what useItem() returns. |
S is the type of your step list: typeof checkout.steps.
import type { Stepper } from "@stepperize/react";
function Actions({ stepper }: { stepper: Stepper<typeof checkout.steps> }) {
return <button onClick={() => stepper.next()}>Continue</button>;
}In a file that also uses the Stepper primitives of a definition, give one of
the two another name: import type { Stepper as StepperOf } from "@stepperize/react".
Last updated on