Stepper
What useStepper and useStepperContext return.
A stepper is a picture of the flow at one moment, plus the actions that change it. Every change produces a new stepper; the one you hold does not change. See The flow and the stepper.
State
| Property | Type | Description |
|---|---|---|
steps | Step[] | The steps of the definition. |
current | Step | The step being shown, with all its fields. |
index | number | Position of current in steps. |
isFirst | boolean | current is the first step. |
isLast | boolean | next() finishes the flow. See Branching. |
progress | number | Position of current in steps, from 0 to 1. |
data | object | The data of every step, by id, as it was typed: drafts included. Typed by each step's schema input. |
output | object | What the schema of each complete step produced, by id: transforms and defaults applied. Typed by each step's schema output. See Draft data and validated output. |
isPending | boolean | An async schema, guard or onFinish is running. |
isFinished | boolean | next() completed a final step and onFinish settled. false again as soon as the flow changes. See Finishing. |
Queries
| Method | Returns | Description |
|---|---|---|
state(id) | "pending" | "current" | "complete" | complete means next() validated the step and moved on, and its data has not changed since. The step being shown is always current. See Step state. |
issues(id?) | Issue[] | undefined | Issues of the last failed validation of a step (a rejected next() or a validate()), the current one by default, until its data changes. |
canGoTo(id) | boolean | Whether goTo(id) is allowed right now. Does not run the guard. |
match(handlers) | The handler's result | Runs the handler of the current step with (step, data). Exhaustive. |
snapshot() | Snapshot | Everything needed to resume the flow. |
Actions
| Method | Description |
|---|---|
next(data?) | Saves data for the current step, validates it and moves on. On a final step it finishes the flow. |
prev() | Goes back to the step the person came from, or to the previous step in the list. Never validates. |
goTo(id) | Jumps to a step. Does not validate; linear and the guard apply. |
validate(id?) | Checks the data of a step, the current one by default, against its schema without moving. Resolves with the issues, or undefined when it is valid. |
setData(id, data) | Replaces the data of a step, right away. A complete step whose data changes is no longer complete. |
reset() | Back to the initial snapshot. Cancels a running move. |
restore(snapshot) | Replaces the parts of the state you pass and keeps the rest, without validation or guards. Cancels a running move. |
The actions are the same functions on every stepper of a flow, and they always
act on the flow as it is now. setData, reset and restore return nothing.
validate
const issues = await stepper.validate(); // the current step
if (issues) showErrors(issues);
await stepper.validate("shipping"); // any step, by idvalidate runs the step's schema on its stored data and remembers the
result: stepper.issues(id) returns the same issues until the data changes. It
does not move, does not mark the step complete, does not run the guard and does
not call onChange. A step without a schema is always valid.
setData and completion
A step is complete while its data is the data next() validated. Writing a
different value with setData makes the step not complete and removes its
entry from output. In a linear flow the
steps completed after it stop being complete too, so they are reached through
next() again. Writing the same value (compared with Object.is) does
nothing: no change, no onChange.
Results
next, prev and goTo resolve with a result and do not throw for expected
outcomes.
type Result =
| { accepted: true; to: StepId | null; data: FlowData }
| { accepted: false; reason: Reason; issues?: Issue[] };to is null when the flow finished.
| Reason | Meaning |
|---|---|
invalid | The step's schema rejected its data. issues says why. |
guard | Your guard returned false. |
policy | linear does not allow jumping to that step. |
pending | Another move is still running. |
boundary | prev() was called with nowhere to go back to. |
finished | next() was called after the flow finished. Any move, a setData with a new value, reset() or restore() reopens it. |
cancelled | reset(), restore() or unmounting interrupted the move. |
const result = await stepper.next(values);
if (result.accepted) {
if (result.to === null) toast("Done");
} else if (result.reason === "invalid") {
showErrors(result.issues);
}What throws
- An exception from your own schema, guard or
nextbranch is not caught: the promise rejects with it, and the flow stays where it was. - An exception or a rejected promise from
onFinishrejectsnext()too. The final step is already complete, but the flow is not finished, sonext()can be called again. goToandsetDatawith an id that is not in the definition throw SZ102 immediately. TypeScript prevents it unless the id was cast.
Timing
A move with nothing asynchronous in it is finished when the call returns: the
flow has already changed, and the promise is already resolved. "pending"
only happens while an async schema, guard or onFinish is running.
stepper.next(); // moves to the second step
stepper.next(); // moves to the third: the first call had finishedIn an event handler this means two calls in a row make two moves. To make one move depend on the other, await the result.
Last updated on