Stepperize v9Explore the changes
Skip to Content
Stepperize

The flow and the stepper

The three objects you work with, and how they relate.

Three words are used throughout these docs. They are different things.

NameWhat it isWhere it comes from
DefinitionThe typed description of the steps, with hooks and components bound to it. Holds no state.defineStepper(steps)
FlowOne running instance: the current step, the data of every step, which steps are complete.useStepper(), Provider, Stepper.Root or create() each create one
StepperWhat your component reads: a picture of the flow at one moment, plus the actions that change it.Returned by useStepper() and useStepperContext()
const checkout = defineStepper([{ id: "shipping" }, { id: "payment" }, { id: "review" }]); // definition

function Checkout() {
  const stepper = checkout.useStepper(); // creates a flow, returns its stepper
  return <p>{stepper.current.id}</p>;
}

One flat object

Everything you read and everything you do is directly on the stepper. There are no nested namespaces to learn.

stepper.current; // the step being shown, with your fields
stepper.index; // its position
stepper.data; // the data of every step
stepper.next(values); // save, validate and move forward
stepper.prev(); // go back

Most flows ship with six members:

MemberWhat it gives you
currentThe step being shown.
match({...})Exhaustive rendering by step id.
next(data?), prev()Move through the flow.
isFirst, isLastWhat your Back and Continue buttons need.
dataWhat each step has saved.

The rest (branching, snapshots, jumping to a step) is there when you need it. The full reference lists every member.

Derived from one position

You only express intent: go next, go back, jump to review. The stepper derives the consequences from the flow's state, so they can never disagree.

const flow = checkout.create(); // the same flow, without React

flow.index; // 0
flow.isFirst; // true
flow.progress; // 0

await flow.next();

flow.index; // 1
flow.current.id; // "payment"
flow.state("shipping"); // "complete"
flow.progress; // 0.5

A stepper is a snapshot in time

Each change produces a new stepper, and your component re-renders with it. The one you already hold does not change. That is what makes it safe to compare in selectors and effects, and it has one consequence worth knowing: after an await, the stepper captured by your handler still describes the moment before the move.

async function onContinue() {
  const result = await stepper.next(values);

  stepper.current.id; // still the step you were on
  if (result.accepted) result.to; // where the flow went, or null if it finished
}

Read what happened from the result, not from the stepper in scope. The actions themselves (next, prev, goTo, setData...) always act on the live flow, so calling them from an old stepper is fine.

Who owns the flow

The component that creates the flow owns it and configures it.

You writeThe flow lives
checkout.useStepper(options)In that component. Each call is a separate flow.
<checkout.Provider {...options}>In the provider, shared with everything below.
<Stepper.Root {...options}>In the root, shared with everything below.
checkout.create(options)Wherever you keep the returned object.

Options go on the owner. Components below a Provider or a Stepper.Root read the flow with useStepperContext() and cannot reconfigure it. See Shared state.

Next: the lifecycle of a move.

Edit on GitHub

Last updated on

On this page