The flow and the stepper
The three objects you work with, and how they relate.
Three words are used throughout these docs. They are different things.
| Name | What it is | Where it comes from |
|---|---|---|
| Definition | The typed description of the steps, with hooks and components bound to it. Holds no state. | defineStepper(steps) |
| Flow | One running instance: the current step, the data of every step, which steps are complete. | useStepper(), Provider, Stepper.Root or create() each create one |
| Stepper | What your component reads: a picture of the flow at one moment, plus the actions that change it. | Returned by useStepper() and useStepperContext() |
const checkout = defineStepper([{ id: "shipping" }, { id: "payment" }, { id: "review" }]); // definition
function Checkout() {
const stepper = checkout.useStepper(); // creates a flow, returns its stepper
return <p>{stepper.current.id}</p>;
}One flat object
Everything you read and everything you do is directly on the stepper. There are no nested namespaces to learn.
stepper.current; // the step being shown, with your fields
stepper.index; // its position
stepper.data; // the data of every step
stepper.next(values); // save, validate and move forward
stepper.prev(); // go backMost flows ship with six members:
| Member | What it gives you |
|---|---|
current | The step being shown. |
match({...}) | Exhaustive rendering by step id. |
next(data?), prev() | Move through the flow. |
isFirst, isLast | What your Back and Continue buttons need. |
data | What each step has saved. |
The rest (branching, snapshots, jumping to a step) is there when you need it. The full reference lists every member.
Derived from one position
You only express intent: go next, go back, jump to review. The stepper derives the consequences from the flow's state, so they can never disagree.
const flow = checkout.create(); // the same flow, without React
flow.index; // 0
flow.isFirst; // true
flow.progress; // 0
await flow.next();
flow.index; // 1
flow.current.id; // "payment"
flow.state("shipping"); // "complete"
flow.progress; // 0.5A stepper is a snapshot in time
Each change produces a new stepper, and your component re-renders with it. The
one you already hold does not change. That is what makes it safe to compare in
selectors and effects, and it has one consequence worth knowing: after an
await, the stepper captured by your handler still describes the moment
before the move.
async function onContinue() {
const result = await stepper.next(values);
stepper.current.id; // still the step you were on
if (result.accepted) result.to; // where the flow went, or null if it finished
}Read what happened from the result, not from the stepper in scope. The actions
themselves (next, prev, goTo, setData...) always act on the live flow,
so calling them from an old stepper is fine.
Who owns the flow
The component that creates the flow owns it and configures it.
| You write | The flow lives |
|---|---|
checkout.useStepper(options) | In that component. Each call is a separate flow. |
<checkout.Provider {...options}> | In the provider, shared with everything below. |
<Stepper.Root {...options}> | In the root, shared with everything below. |
checkout.create(options) | Wherever you keep the returned object. |
Options go on the owner. Components below a Provider or a Stepper.Root
read the flow with useStepperContext() and cannot reconfigure it. See
Shared state.
Next: the lifecycle of a move.
Last updated on