Stepperize v9Explore the changes
Skip to Content
Stepperize

Step state

Pending, current and complete, and what moves a step between them.

Every step is in exactly one state.

StateMeaning
currentThe step being shown.
completenext() validated this step and moved on, and its data has not changed since.
pendingEverything else: not reached yet, left without being validated, or edited after it was validated.
stepper.state("shipping"); // "pending" | "current" | "complete"

The primitives expose the same value as data-state on each item, trigger and indicator.

What completes a step

Only next() does, when the step's data passes its schema and the guard allows the move. That includes the final next() that finishes the flow.

prev() and goTo() never complete the step they leave, and never validate it. Neither does validate(): it checks, and completing stays with next().

const flow = checkout.create(); // shipping, payment, review

await flow.next({ address: "1 Main St" });
flow.state("shipping"); // "complete"
flow.state("payment"); // "current"

await flow.goTo("review"); // jumps over nothing, but leaves payment unvalidated
flow.state("payment"); // "pending"

So complete is not the same as "before the current step". A step someone jumped over, or skipped through a branch, stays pending.

Going back

Completion is remembered. When someone returns to a completed step it reads current while they are on it, and complete again once they leave, however they leave.

await flow.goTo("shipping");
flow.state("shipping"); // "current"

await flow.goTo("payment");
flow.state("shipping"); // "complete" again

What undoes completion

A step is complete for as long as its data is what next() validated. Two things end that:

  • setData writes a different value to it. Writing the same value (compared with Object.is) changes nothing.
  • A next(data) called from it is rejected by the schema.
await flow.goTo("shipping");
flow.setData("shipping", { address: "" });

await flow.goTo("payment");
flow.state("shipping"); // "pending": it was edited and not validated again

The step's entry in stepper.output goes away with it. Calling next() from the step validates it and completes it again.

In a linear flow the steps completed after the edited one stop being complete as well. Their data is kept, but they have to be reached through next() again, which is what guarantees that nobody gets past a step whose data was never validated. See Editing a step that was already complete.

What completion is used for

  • Reachability. In a linear flow, goTo and the triggers reach the current step and the completed ones. Nothing else.
  • Styling. data-[state=complete] is what draws the check mark.
  • Your own rules. For example, enabling a submit button:
const ready = stepper.steps.every(
  (step) => step.id === stepper.current.id || stepper.state(step.id) === "complete",
);

The list of completed ids is part of the snapshot, in the order the steps were completed, so a resumed flow keeps its check marks.

Styling by position instead

If your design fills every step before the current one, whatever happened in them, compare positions:

<Stepper.List>
  {(step, index) => (
    <Stepper.Item data-passed={index < stepper.index || undefined}>
      <Stepper.Title />
    </Stepper.Item>
  )}
</Stepper.List>

Marking a step complete yourself

Completion normally follows validation, and that is what keeps it meaningful. When it comes from somewhere else, such as a server that already holds the data, set it through the snapshot:

// At the start
checkout.useStepper({ snapshot: { step: "payment", complete: ["shipping"] } });

// Later
stepper.restore({ complete: [...stepper.snapshot().complete, "payment"] });

Invalid is separate

A step whose last next() or validate() was rejected by its schema is not in a fourth state: it is still current, or pending if it is not the one being shown. Read stepper.issues(id), or style data-invalid, which is present until that step's data changes.

Next: moving between steps.

Edit on GitHub

Last updated on

On this page