Options
Everything a flow can be configured with.
The same options are accepted by defineStepper (as defaults), useStepper,
Provider, Stepper.Root and create. Callbacks always see your latest
props: there is nothing to memoize.
| Option | Type | Description |
|---|---|---|
linear | boolean | Only move forward through next(). Default false. |
next | object | Where each step leads. |
guard | function | Runs before every move and can cancel it. |
snapshot | Partial<Snapshot> | Where the flow starts. Read once. |
step | string | null | An outside value the flow follows, such as the URL. |
onChange | (snapshot) => void | Called after the step, the data or the completion changes. |
onFinish | (output, data) => void | Promise | Called once when the flow ends. |
onInvalidStep | (current) => void | Called when the flow cannot follow step. |
Options passed to a flow are merged over the definition's defaults, one option at a time.
const checkout = defineStepper(steps, { linear: true });
checkout.useStepper(); // linear
checkout.useStepper({ linear: false }); // not linearlinear
In a linear flow, goTo and the triggers only reach the current step and the
steps already complete. Everything else
is reached through next(), which validates. prev() is always allowed.
Editing a complete step with setData makes it, and the steps completed after
it, not complete: nothing past an edited step can be reached without
validating it again.
Without linear, any step can be opened at any time.
See Linear flows.
next
A map from step id to where it leads. See Branching.
next: {
account: (data) => (data.type === "team" ? "team" : "payment"),
profile: (_data, flow) => (flow.account?.type === "team" ? "invite" : "done"),
rejected: null,
}- A function receives the step's validated data, then the data of every
step, and returns a step id, or
nullto end the flow. nullends the flow at that step.- No entry: the following step in the list, or the end after the last one.
A branch that returns an id that is not in the definition makes next()
reject with SZ102.
guard
guard: async ({ from, to, direction, data, signal }) => {
if (direction !== "next") return;
const response = await fetch("/api/check", {
method: "POST",
body: JSON.stringify(data),
signal,
});
return response.ok;
}Runs after validation and before every next, prev and goTo. Return
false to cancel the move; anything else, including nothing, allows it. It
may be async.
| Field | Description |
|---|---|
from | The step being left. |
to | The step being entered, or null when the flow is finishing. |
direction | "next", "prev" or "goTo". |
data | The data of every step as it will be if the move is accepted. |
signal | Aborted if the move is cancelled by reset, restore or unmounting. |
It is not called by setData, reset or restore. See
Guard a move.
snapshot
type Snapshot = {
step: string; // the current step
history: string[]; // the path taken, which prev() walks back
data: object; // the data of every step, by id
complete: string[]; // the steps next() has validated, in that order
};Pass any part of it. It is read when the flow is created; to apply one later,
call stepper.restore(snapshot). Ids that are not in the definition are
dropped from step, history and complete.
A snapshot does not carry output. Steps restored as complete get theirs when
the flow finishes: see onFinish.
reset() returns to this snapshot. See
Saving and resuming.
step
A step id that lives somewhere else, typically the URL. The flow starts on it
and goes to it whenever the value changes, the way goTo would: linear and
the guard apply. Any string is accepted; null and undefined mean "nothing
to follow".
When both step and snapshot.step are given, step wins if the flow is
allowed to be there.
See The step in the URL.
onChange
Called with the new snapshot after anything a saved copy should know about:
- an accepted
next,prevorgoTo, - a
next()rejected by the schema, because the data that was passed is kept, setDatawith a new value,resetandrestore.
It is not called when only isPending, isFinished or the issues change (so
not by validate()), when a guard refuses a move, or when the flow cannot
follow step.
Because setData calls it, debounce slow writes if you save drafts while
typing.
onFinish
Called once when next() completes a final step: the last step of the list, a
step whose next entry is null, or a branch that returned null.
onFinish: async (output, data) => {
await api.createOrder(output);
},| Argument | What it holds |
|---|---|
output | What the schema of every complete step produced: transforms, coercions and defaults applied. Typed by each schema's output. |
data | Every step as it was typed, drafts of steps that were never completed included. Typed by each schema's input. |
Return a promise and the flow stays pending (isPending) until it settles.
When it resolves, isFinished becomes true. When it rejects, next() rejects
with the same error and the flow is not finished, so the person can try again.
The flow stays on that step. Once finished, next() is refused with the reason
finished, so a second press does not submit twice. Any move, a setData with
a new value, reset() or restore() reopens the flow. See
Finishing the flow.
Steps that were restored as complete from a snapshot have no output yet, so
they are validated once more right before onFinish. If one fails, the flow
does not finish: next() resolves with invalid, the issues are stored under
that step (stepper.issues(id)) and the step is no longer complete.
onInvalidStep
Called with the id of the step the flow is on when it cannot follow step:
- the value is not a step of the definition,
- a linear flow does not allow that step yet,
- the guard refused the move,
- or another move was still running.
Use it to correct the source without adding a history entry:
onInvalidStep: (current) => router.replace(`/checkout/${current}`),Last updated on