Stepperize v9Explore the changes
Skip to Content
Stepperize

The step in the URL

Keep the current step and the address bar in sync.

Three options do it. step makes the flow follow the URL, onChange updates the URL when the flow moves, and onInvalidStep corrects a URL the flow cannot follow.

function Checkout() {
  const { step } = useParams();
  const router = useRouter();

  const stepper = checkout.useStepper({
    step,
    onChange: (snapshot) => {
      if (snapshot.step !== step) router.push(`/checkout/${snapshot.step}`);
    },
    onInvalidStep: (current) => router.replace(`/checkout/${current}`),
  });
}

The example uses a Next.js style router. Any router works: the options only need a string to read and two functions to call.

How it behaves

Something happensThe flowYour callback
The page opens on /checkout/paymentStarts on payment, if it is allowed toNone
The person presses ContinueMoves to the next steponChange, where you push the new URL
The person presses the browser's Back buttonGoes to the step in the URL, like goToonChange, with the step already matching
The URL names a step that does not existStays where it isonInvalidStep, where you replace the URL
The URL names a step that is not reachable yetStays where it isonInvalidStep

step accepts any string, null or undefined, so you can pass what the router gives you without checking it first.

Why two callbacks

They need different history behavior.

  • A real move should push an entry, so the Back button returns to the previous step.
  • A correction should replace the bad entry, so the Back button does not land on it again.

onChange is only called when something changed, and onInvalidStep only when the flow refused to follow, so each can do the right thing without guessing.

It cannot be used to skip steps

Following the URL behaves like goTo: linear and the guard still apply. Someone who opens /checkout/payment directly in a linear flow starts on the first step, onInvalidStep is called with that step, and the URL is corrected.

onInvalidStep receives the step the flow is on. It runs when the value is:

  • an id that is not in the definition,
  • a step a linear flow does not allow yet,
  • a step the guard refused,
  • or any step while another move is still running.

With a saved snapshot

Use both. The snapshot restores the data and the completed steps, so a link to a step the person already completed is honored after a reload.

checkout.useStepper({
  step,
  snapshot: savedSnapshot,
  onChange: (snapshot) => {
    save(snapshot);
    if (snapshot.step !== step) router.push(`/checkout/${snapshot.step}`);
  },
  onInvalidStep: (current) => router.replace(`/checkout/${current}`),
});

When step and snapshot.step disagree, step wins if the flow is allowed to be there.

Search params

Nothing changes when the step is in the query string.

const [params, setParams] = useSearchParams();
const step = params.get("step");

checkout.useStepper({
  step,
  onChange: (snapshot) => {
    if (snapshot.step !== step) setParams({ step: snapshot.step });
  },
  onInvalidStep: (current) => setParams({ step: current }, { replace: true }),
});

With a Provider or Stepper.Root

The same three options are props of the owner.

<checkout.Provider
  step={step}
  onChange={(snapshot) => snapshot.step !== step && router.push(`/checkout/${snapshot.step}`)}
  onInvalidStep={(current) => router.replace(`/checkout/${current}`)}
>

Details worth knowing

  • onChange is also called when data changes, which is why the examples compare snapshot.step with the URL before navigating.
  • The flow only acts when the value of step changes. Re-rendering with the same value while the URL catches up does not pull the flow back.
  • reset() returns to the flow's initial snapshot, not to the URL. onChange then reports the new step and the URL follows.
  • On the server, pass the same route value so the first render shows the right step.
Edit on GitHub

Last updated on

On this page