The lifecycle of a move
What happens between calling next() and the step changing.
next, prev and goTo are the three moves. They follow the same sequence,
commit once, and resolve with what happened.
The sequence of next(data)
- Gate. If the flow already finished, resolve
{ accepted: false, reason: "finished" }. If another move is still running, resolve{ accepted: false, reason: "pending" }. Either way, stop. - Validate. Run the data against the current step's schema.
datais the argument you passed, or what the step already has stored. Steps without a schema pass. If validation fails: store the data and the issues, stay on the step and resolve{ accepted: false, reason: "invalid", issues }. A step that was complete is no longer. - Pick the target. The step's entry in the
nextmap, or the following step in the list, or the end of the flow. - Guard. Call your
guard, if there is one, with where the move is going and the data as it will be. If it returnsfalse: change nothing and resolve{ accepted: false, reason: "guard" }. - Commit. In one update: save the data, mark the step complete, keep the
schema's output in
stepper.output, extend the history and change the step. Your components render once. - Notify. Call
onChangewith the new snapshot. - Finish. If the flow ended, call
onFinish(output, data)and wait for it when it returns a promise. ThenisFinishedbecomestrue. - Resolve
{ accepted: true, to, data }.
const result = await stepper.next(values);
if (result.accepted) {
result.to; // the new step id, or null when the flow finished
} else {
result.reason; // "invalid" | "guard" | "policy" | "pending" | "boundary" | "finished" | "cancelled"
}What happens to the data when a move is refused
| Refused by | The data you passed |
|---|---|
Validation (invalid) | Kept as the step's data, with its issues, so the form still shows what was typed. |
The guard (guard) | Discarded. The flow is exactly as it was. |
Another move running (pending) | Discarded. |
A finished flow (finished) | Discarded. |
If you need the data saved no matter what, write it with setData first.
prev() and goTo(id)
They skip validation and go straight to the guard.
| Move | Target | Refused with |
|---|---|---|
prev() | The step you came from. Without a path to walk back, the previous step in the list. | boundary when there is nowhere to go. |
goTo(id) | The step you name. | policy when the flow is linear and the step is not reachable yet. |
goTo to the step you are already on resolves as accepted and does nothing.
goTo with an id that is not in the definition throws
SZ102.
The path, and how prev() uses it
The flow remembers the steps walked to reach the current one. next and
goTo add the step being left; going back to a step that is on the path
removes everything after it.
const flow = checkout.create(); // shipping, payment, review
await flow.next(); // at payment path: shipping
await flow.next(); // at review path: shipping, payment
await flow.goTo("shipping"); // at shipping path: (empty)
await flow.goTo("review"); // at review path: shipping
await flow.prev(); // at shipping: where you came from, not "payment"This is what makes Back correct in a branching flow: it returns along the branch the person actually took.
Writes that are not moves
| Call | What it does | Validation and guard |
|---|---|---|
setData(id, data) | Replaces the data of a step, right away. A complete step whose data changes is no longer complete. | None. |
validate(id?) | Runs a step's schema on its stored data and remembers the issues. Changes nothing else. | The schema only. |
restore(snapshot) | Replaces any part of the state. | None. Cancels a running move. |
reset() | Back to the snapshot the flow started with. | None. Cancels a running move. |
setData, restore and reset call onChange; validate does not. None of
them calls the guard.
Pending and cancellation
A move is synchronous unless something in it is not. When the schema, the
guard or onFinish returns a promise:
stepper.isPendingistrueuntil it settles.- Any other move resolves with
reason: "pending", so a double click cannot run the same check twice. canGoTo(id)isfalse, and the primitives mark their buttons as disabled.reset(),restore()or unmounting cancels it. The cancelled move resolves withreason: "cancelled", and thesignalyour guard received is aborted.
checkout.useStepper({
guard: async ({ from, data, signal }) => {
if (from.id !== "payment") return;
const response = await fetch("/api/authorize", {
method: "POST",
body: JSON.stringify(data.payment),
signal,
});
return response.ok;
},
});With synchronous schemas and guards nothing is ever pending: the step has
already changed when next() returns its promise, and there is no flicker of
a loading state.
Errors
A refused move is not an error: the promise resolves. If your schema or guard
throws, the promise rejects with that error, the flow stays where it was, and
isPending goes back to false.
onFinish is the one callback that runs after the commit. If it throws or its
promise rejects, next() rejects too: the final step stays complete, but
isFinished stays false, and calling next() again runs onFinish again.
A promise is always truthy, so check the result, not the call:
// Wrong: always true.
if (stepper.next()) showConfetti();
// Right
const result = await stepper.next();
if (result.accepted) showConfetti();Next: step state.
Last updated on