Stepperize v9Explore the changes
Skip to Content
Stepperize

Migrating from v8

What changed in v9, and a codemod that rewrites most of it.

v9 keeps the idea of v8, one typed definition, and removes most of what you had to wire by hand:

  • next() validates the step. You no longer write a guard for that.
  • One snapshot replaces the controlled data and completed props.
  • One state per step replaces positional status plus explicit completion.
  • Branching is declared once, in a next map.

1. Update

npm install @stepperize/react@^9

React 18 and 19 are still supported.

2. Run the codemod

Commit your work first.

npx @stepperize/codemod v9 src --check

Pass one or more files or directories. It rewrites .ts, .tsx, .js and .jsx files. The codemod itself needs Node 22.18 or later.

Option
--checkType-check the migrated files and list the errors left in them
--dryReport what would change without writing anything
--jsonPrint the report as JSON, for scripts and coding agents
--no-typesDo not use the project's TypeScript to find steppers

When it finishes it prints what is left for you: each kind of comment it wrote with the files it is in, the rewrites worth a look, and the style sheets that still use the v8 attributes and, with --check, the type errors in what it migrated. Then:

  1. Run your formatter. Lines the codemod did not have to touch stay as they were; a rewritten statement keeps your quotes and indentation, but not always its line breaks.
  2. Search for the comments it left. Each one sits above a statement that needs a decision, and says what replaces the old API.
  3. Fix the type errors --check listed. They are v8 calls the codemod could not rewrite.
grep -rn "TODO(stepperize-v9)" src

What it rewrites

v8v9
stepper.idstepper.current.id
stepper.countstepper.steps.length
stepper.is("a")stepper.current.id === "a"
stepper.canPrev, stepper.canNext!stepper.isFirst && !stepper.isPending, !stepper.isLast && !stepper.isPending
stepper.isComplete(id)stepper.state(id) === "complete"
stepper.completedstepper.snapshot().complete
stepper.data.get("a"), data.get()stepper.data.a, stepper.data[stepper.current.id]
stepper.data.all()stepper.data
stepper.data.set("a", value)stepper.setData("a", value)
stepper.data.update("a", fn)stepper.setData("a", fn(stepper.data.a))
stepper.next({ data, complete: true })stepper.next(data)
<Stepper.Root>{({ stepper }) => …}<Stepper.Root>{(stepper) => …}
<Stepper.Items>{fn}</Stepper.Items> inside List<Stepper.List>{fn}</Stepper.List>
<Stepper.Actions>, <Stepper.Separator><div>, <hr>
beforeStepChangeguard
A guard that only returned (await validate()).successRemoved: next() validates
stepper.status(id) === "active"stepper.state(id) === "current"
defaultStep, defaultData, defaultCompletedsnapshot: { step, data, complete }

What it follows

The codemod only rewrites a value it can tell is a stepper: the result of useStepper() and useStepperContext(), the argument of a selector, the function child of Stepper.Root, anything typed as a Stepper, a stepper read from a ref typed as one, and what your own hooks return when they are in the same file.

When the project has a tsconfig.json and TypeScript 5 or 6 installed, it also asks the type checker, which follows a stepper through props, your own context and other files. Otherwise it works from the syntax alone. Either way, where it finds the unmistakable v8 names on a value it could not follow (.data.get(), .data.set(), .canNext, .isComplete() and the like) it leaves a comment instead of guessing.

Styles

In files that use a stepper, the codemod renames the selectors, both as Tailwind variants (data-[status=active]:) and as CSS attribute selectors inside strings:

v8v9
data-status="active"data-state="current"
data-status="previous"data-state="complete", with the difference explained below
data-status="upcoming"data-state="pending"
data-completedata-state="complete"

It lists the files where previous became complete, because the two only match in a flow walked with next(). Style sheets are read but never rewritten: it prints each line that still mentions data-status or data-complete for you to update.

3. Go through the rest

A coding agent can make most of these decisions for you: see Migrating with an AI agent for a prompt that runs the codemod and resolves what it leaves.

The sections below cover everything the codemod flags, in the order you are most likely to meet it.

Validation moved into next()

// v8
const stepper = checkout.useStepper({
  beforeStepChange: async ({ direction, validate }) => {
    if (direction !== "next") return true;
    return (await validate()).success;
  },
});
await stepper.next({ data: values, complete: true });

// v9
const stepper = checkout.useStepper();
await stepper.next(values);

next() validates against the step's schema, marks the step complete and returns the issues when it fails. Delete guards that only called validate(). The guard still exists for other checks, and is now called guard.

v8v9
beforeStepChangeguard
ctx.validate() inside the guardNot needed: validation runs before the guard
Errors kept in your own state after validate()stepper.issues(id)
stepper.validate(id)Still stepper.validate(id), with a different result: it resolves with the issues, or undefined when the step is valid. next() validates by itself, so most calls can go
direction: "goto"direction: "goTo"
direction: "reset"Removed: reset() does not run the guard
ctx.fromIndex, ctx.toIndex, ctx.statusesctx.from, ctx.to (null when finishing)
next({ data, complete })next(data)
result.fromRemoved. Read the step before calling
reason: "same-step", "invalid-step"Removed. goTo to the current step is accepted; an unknown id throws

Two behaviors changed with it:

  • A rejected next(data) keeps the data when the schema is what rejected it, so the form still shows what was typed. In v8 a rejected payload was discarded. A move the guard refuses still discards it.
  • next() on the last step finishes the flow. In v8 it returned boundary. Move what ran after your last step to onFinish, and replace custom "submit" buttons with next() if you want it validated. onFinish runs once and receives (output, data): the schemas' output first, then what was typed. Return the promise of your request from it, and read stepper.isFinished instead of keeping a "submitted" state. Calling next() again after that resolves with the new reason finished.
  • Editing a complete step undoes its completion. A setData with a new value on a complete step makes it not complete, and in a linear flow the steps completed after it too. In v8 completion only changed when you set it. See What undoes completion.

Controlled props became a snapshot

// v8
checkout.useStepper({
  data,
  onDataChange: setData,
  completed,
  onCompletedChange: setCompleted,
});

// v9
checkout.useStepper({
  snapshot: saved,
  onChange: save,
});

The flow always owns its state now. You give it a starting point and you are told about every change; to replace the state later, call restore().

v8v9
defaultStep, defaultData, defaultCompletedsnapshot: { step, data, complete }
data + onDataChangesnapshot + onChange, and restore({ data }) to replace it later
completed + onCompletedChangesnapshot + onChange, and restore({ complete })
onStepChange(id, ctx)onChange(snapshot); read snapshot.step. It also runs when data changes

See Saving and resuming.

The step in the URL

step and onInvalidStep still exist, with two differences.

// v8
checkout.useStepper({
  step,
  onStepChange: (id) => router.push(`/checkout/${id}`),
  onInvalidStep: () => router.replace("/checkout/shipping"),
});

// v9
checkout.useStepper({
  step,
  onChange: (snapshot) => snapshot.step !== step && router.push(`/checkout/${snapshot.step}`),
  onInvalidStep: (current) => router.replace(`/checkout/${current}`),
});
v8v9
A change of step is authoritative and skips the guardIt behaves like goTo: linear and the guard apply
onInvalidStep(raw) runs for unknown idsonInvalidStep(current) receives the step the flow is on, and also runs when linear or the guard refuse the step
Passing step without onStepChange freezes the stepperThe flow keeps moving; step is only followed when its value changes
definition.parseStep(value)Not needed: step accepts any string

See The step in the URL.

One state per step

v8 had a positional status and a separate, explicit completion. v9 has one state per step, and a step becomes complete when next() validates it.

v8v9
stepper.status(id): active, previous, upcomingstepper.state(id): current, complete, pending
stepper.isComplete(id)stepper.state(id) === "complete"
stepper.completedstepper.snapshot().complete
stepper.setComplete(id)Let next() do it, or stepper.restore({ complete: [...stepper.snapshot().complete, id] })
data-status, data-completedata-state

previous and complete are not the same thing. A step the person jumped over is before the current one but was never completed, and a completed step they went back past is still complete, until its data is edited. If you styled by position, compare indexes instead; see Step state.

Linear flows

In v8, linear allowed the previous steps, the current one and the immediate next one. In v9 it allows the current step and the completed ones, and the only way forward is next(). A trigger for the following step is therefore disabled until the current step is completed.

Data is a plain object

v8v9
stepper.data.get("shipping")stepper.data.shipping
stepper.data.all()stepper.data
stepper.data.set("shipping", value)stepper.setData("shipping", value)
stepper.data.update(id, fn)stepper.setData(id, fn(stepper.data[id]))
stepper.data.clear(id)stepper.restore({ data: { ...stepper.data, [id]: undefined } })
stepper.data.reset()stepper.restore({ data: {} })

stepper.data is replaced, not mutated, on every write, so it is safe to use in dependency arrays and selectors.

Derived values

v8v9
stepper.idstepper.current.id
stepper.countstepper.steps.length
stepper.is("review")stepper.current.id === "review"
stepper.canPrev!stepper.isFirst && !stepper.isPending
stepper.canNext!stepper.isPending if the last step should finish the flow; otherwise !stepper.isLast && !stepper.isPending
isFirst, isLast, progressUnchanged. isLast now means "next() finishes the flow", so it knows about branches
v8v9
goTo(id, { bypassPolicy: true })Describe the jump in the next map and call next()
goTo(id, { data }), prev({ data })setData(...), then move
reset({ keepData: true })restore({ step: firstStepId, history: [], complete: [] })
reset({ keepData: true, keepCompleted: true })restore({ step: firstStepId, history: [] })
await reset()reset() is synchronous and does not run the guard
prev() goes to the previous step in the listprev() goes to the step the person came from

Primitives

v8v9
<Stepper.Root>{({ stepper }) => …}<Stepper.Root>{(stepper) => …}
<Stepper.Items>{fn}</Stepper.Items> inside List<Stepper.List>{fn}</Stepper.List>
Stepper.ActionsA div
Stepper.SeparatorThe codemod leaves an hr. Prefer CSS on the items: see Styling
Title renders h4, Description renders pBoth render span. Use render for another element
Stepper.Next is disabled on the last stepIt finishes the flow
@stepperize/react/primitivesUse the Stepper of your definition

The markup now follows the flow: a linear stepper is an ordered list of steps with aria-current="step" instead of tabs. If your tests query by role, a linear flow has buttons where it had tabs. See Accessibility.

Definition helpers

v8v9
definition.get(id)definition.steps.find((step) => step.id === id)
definition.at(index)definition.steps[index]
definition.parseStep(value)Pass the value as the step option
definition.validate(id, value)stepper.validate(id) for the data the flow holds. For any other value, call the schema: schema["~standard"].validate(value)
useStepperContext(selector, isEqual)useStepperContext(selector)
Types Get.Id, InputOf, OutputOf, NavigationResultId, Input, Output, Result
Utilities exported by @stepperize/coreRemoved. The core now exports createStepper

New in v9

Not needed to migrate, but worth knowing once you have:

  • Branching with a typed next map, and flows with more than one ending.
  • issues(): the errors of the last attempt, without keeping them in your own state.
  • stepper.output: what each schema produced, next to the data as it was typed.
  • isFinished, and an onFinish that can be awaited.
  • The flow without React, for tests and servers.
  • Primitives that pick the right ARIA pattern, move focus and announce step changes.
Edit on GitHub

Last updated on

On this page