Step state
Pending, current and complete, and what moves a step between them.
Every step is in exactly one state.
| State | Meaning |
|---|---|
current | The step being shown. |
complete | next() validated this step and moved on, and its data has not changed since. |
pending | Everything 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" againWhat undoes completion
A step is complete for as long as its data is what next() validated. Two
things end that:
setDatawrites a different value to it. Writing the same value (compared withObject.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 againThe 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,
goToand 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.
Last updated on