Stepperize v9Explore the changes
Skip to Content
Stepperize

Local and shared state

Choose who owns a flow, and re-render only what changed.

The name of the hook tells you where the flow lives.

APIWhat it does
checkout.useStepper(options)Creates a flow that belongs to the component. Every call is independent.
checkout.ProviderCreates a flow and shares it with everything below.
checkout.useStepperContext()Reads the flow of the nearest provider of that definition.
checkout.useStepperContext(selector)Reads one part of it, and re-renders only when that part changes.
checkout.Stepper.RootA provider that also renders the container of the primitives.

One definition, many flows

Keep the definition outside your components. It holds the steps and the typed APIs, not a current step, so every owner gets its own flow.

checkout.ts
import { defineStepper } from "@stepperize/react";

export const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
]);

A local flow

Use useStepper() when one component renders the whole flow. Each mounted LocalCheckout has its own step, data and completion.

import { checkout } from "./checkout";

export function LocalCheckout() {
  const stepper = checkout.useStepper();

  return (
    <section>
      <h2>{stepper.current.title}</h2>
      <button type="button" disabled={stepper.isFirst} onClick={() => stepper.prev()}>
        Back
      </button>
      <button type="button" onClick={() => stepper.next()}>
        {stepper.isLast ? "Place order" : "Continue"}
      </button>
    </section>
  );
}

A shared flow

Split the same UI into components. Put one provider above them, and replace the local hook with useStepperContext.

import { checkout } from "./checkout";

export function SharedCheckout() {
  return (
    <checkout.Provider linear onFinish={(output) => console.log(output)}>
      <Header />
      <Panel />
      <Actions />
    </checkout.Provider>
  );
}

function Header() {
  const index = checkout.useStepperContext((stepper) => stepper.index);
  return (
    <p>
      Step {index + 1} of {checkout.steps.length}
    </p>
  );
}

function Panel() {
  const stepper = checkout.useStepperContext();
  return stepper.match({
    shipping: (step) => <h2>{step.title}</h2>,
    payment: (step) => <h2>{step.title}</h2>,
    review: (step) => <h2>{step.title}</h2>,
  });
}

function Actions() {
  const stepper = checkout.useStepperContext();
  return (
    <>
      <button type="button" disabled={stepper.isFirst} onClick={() => stepper.prev()}>
        Back
      </button>
      <button type="button" onClick={() => stepper.next()}>
        {stepper.isLast ? "Place order" : "Continue"}
      </button>
    </>
  );
}

The Provider accepts the same options as useStepper. Options go on the owner: the components below read the flow and call its actions, and cannot reconfigure it.

Header subscribes to the index only, so writing data does not re-render it.

Selectors

Without arguments, useStepperContext() returns the stepper and the component re-renders on every change of the flow. Pass a selector to re-render only when its result changes.

// Re-renders only when the step changes.
const id = checkout.useStepperContext((s) => s.current.id);

// Re-renders only when an async check starts or ends.
const pending = checkout.useStepperContext((s) => s.isPending);

// Re-renders only when the data of this step changes.
const shipping = checkout.useStepperContext((s) => s.data.shipping);

Results are compared by identity. Strings, numbers, booleans and objects the stepper already holds work as you expect. A selector that builds a new object or array is safe, and re-renders on every change, because its result is new each time:

const view = checkout.useStepperContext((s) => ({ id: s.current.id, last: s.isLast }));

Prefer two selectors over one that builds an object.

You rarely need selectors for correctness. Reach for them when a component is expensive to render and only cares about part of the flow, such as a header above a form that writes data on every keystroke.

With the primitives

Stepper.Root is a provider too. Use it in place of Provider when you render the primitives, and read the flow the same way.

const { Stepper } = checkout;

export function PrimitiveCheckout() {
  return (
    <Stepper.Root linear>
      <Stepper.List>
        {() => (
          <Stepper.Item>
            <Stepper.Trigger>
              <Stepper.Title />
            </Stepper.Trigger>
          </Stepper.Item>
        )}
      </Stepper.List>
      <Actions />
    </Stepper.Root>
  );
}

Actions is the same component as before. Each root gets its own element ids, so two checkouts on one page do not collide.

Nested flows and missing providers

  • A Provider inside another Provider of the same definition creates a separate flow for its own subtree.
  • A provider of another definition does not hide the outer one: each definition has its own context.
  • useStepperContext() without a matching provider above throws SZ100. It never creates a flow silently.
  • useStepper() below a provider deliberately creates a new local flow.

Always import the same definition object in the provider and its consumers. Two definitions built from the same steps are two different flows.

Which one to use

You haveUse
One component that renders the whole flowuseStepper()
A header, a body and a footer in different componentsProvider + useStepperContext()
The Stepper primitivesStepper.Root, and useStepperContext() inside it
Two independent flows of the same definition on a pageTwo Providers, or two useStepper() calls
A flow that must outlive its components, or run outside Reactcreate()

Next: building multi-step forms.

Edit on GitHub

Last updated on

On this page