Stepperize v9Explore the changes
Skip to Content
Stepperize

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.

OptionTypeDescription
linearbooleanOnly move forward through next(). Default false.
nextobjectWhere each step leads.
guardfunctionRuns before every move and can cancel it.
snapshotPartial<Snapshot>Where the flow starts. Read once.
stepstring | nullAn outside value the flow follows, such as the URL.
onChange(snapshot) => voidCalled after the step, the data or the completion changes.
onFinish(output, data) => void | PromiseCalled once when the flow ends.
onInvalidStep(current) => voidCalled 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 linear

linear

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 null to end the flow.
  • null ends 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.

FieldDescription
fromThe step being left.
toThe step being entered, or null when the flow is finishing.
direction"next", "prev" or "goTo".
dataThe data of every step as it will be if the move is accepted.
signalAborted 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, prev or goTo,
  • a next() rejected by the schema, because the data that was passed is kept,
  • setData with a new value, reset and restore.

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);
},
ArgumentWhat it holds
outputWhat the schema of every complete step produced: transforms, coercions and defaults applied. Typed by each schema's output.
dataEvery 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}`),
Edit on GitHub

Last updated on

On this page