Stepperize v9Explore the changes
Skip to Content
Stepperize

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

PropertyTypeDescription
stepsStep[]The steps of the definition.
currentStepThe step being shown, with all its fields.
indexnumberPosition of current in steps.
isFirstbooleancurrent is the first step.
isLastbooleannext() finishes the flow. See Branching.
progressnumberPosition of current in steps, from 0 to 1.
dataobjectThe data of every step, by id, as it was typed: drafts included. Typed by each step's schema input.
outputobjectWhat 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.
isPendingbooleanAn async schema, guard or onFinish is running.
isFinishedbooleannext() completed a final step and onFinish settled. false again as soon as the flow changes. See Finishing.

Queries

MethodReturnsDescription
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[] | undefinedIssues 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)booleanWhether goTo(id) is allowed right now. Does not run the guard.
match(handlers)The handler's resultRuns the handler of the current step with (step, data). Exhaustive.
snapshot()SnapshotEverything needed to resume the flow.

Actions

MethodDescription
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 id

validate 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.

ReasonMeaning
invalidThe step's schema rejected its data. issues says why.
guardYour guard returned false.
policylinear does not allow jumping to that step.
pendingAnother move is still running.
boundaryprev() was called with nowhere to go back to.
finishednext() was called after the flow finished. Any move, a setData with a new value, reset() or restore() reopens it.
cancelledreset(), 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 next branch is not caught: the promise rejects with it, and the flow stays where it was.
  • An exception or a rejected promise from onFinish rejects next() too. The final step is already complete, but the flow is not finished, so next() can be called again.
  • goTo and setData with 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 finished

In an event handler this means two calls in a row make two moves. To make one move depend on the other, await the result.

Edit on GitHub

Last updated on

On this page