React Multi-Step Form: The Complete Guide (with Cheat Sheet)

title: "React Multi-Step Form: The Complete Guide (with Cheat Sheet)" description: "Build a React multi-step form that validates per step, survives a refresh, and stays accessible — the mental model, the traps, and a copy-paste cheat sheet." tags: [react, typescript, tutorial, webdev] published: true series: "React Toolbox" package: react-form-wizard-component version: 2.0.0 previousVersion: 1.2.1 ecosystem: react tagline: "Accessible multi-step form wizard for React 17, 18 and 19 — zero dependencies, styled or headless." highlights:

• A wizard is really three things wearing one component's clothes: a cursor, a shared data object, and a per-step gate. Name them and every bug has an address. • Per-step validation does NOT mean four separate forms — one schema, one form, a gate that picks its own fields. • An embedded component should never read prefers-color-scheme. A light page on a dark-mode laptop gets a dark widget on white.

The signup form has four steps. Step three uploads a passport photo and takes eight seconds. A user reaches step four, fat-fingers ⌘R, and lands back on step one with an empty form.

You already know how to fix that. You also know that the moment the step index stops living in useState, the browser back button, the per-step validation, and the focus ring all become your problem too.

Multi-step forms look like two useState calls until you ship one.

By the end of this article you'll be able to:

You've built a React form with controlled inputs and reached for a validation library at least once. TypeScript is used throughout but nothing here depends on it.

Here is the version everyone writes first, in full:

It works. It also ships five bugs, and each one costs about a day:

None of those are hard individually. The problem is that they are five different subsystems, and the naive version has no seam to hang any of them on.

The honest survey, with versions checked against npm at the time of writing:

Two of these deserve a genuine defence.

react-hook-form is the right answer to a different question. It is the best form-state library in the React ecosystem and it is not trying to be a wizard. Nothing below argues against using it — the recipes actively use it.

@stepperize/react is good, current, and well typed. If your design system already owns every pixel and you want nothing but a state machine, use it. It ships no markup on purpose, which means you write the rail, the progress bar, the buttons, and all of the ARIA tabs wiring yourself. That is a feature when you have a design system, and a week of work when you don't.

Three concrete gaps, not vibes.

The peer range that stops the install. react-multistep@7.0.0 declares peerDependencies as { "react": "18.3.1" } — an exact version, not a range. On a React 19 app, npm refuses:

You can --legacy-peer-deps past it. You are then running a component whose author has not tested your React version.

Headless means you own the accessibility. Here is the minimum the tabs pattern asks for, and none of it comes free:

That is a real day of work, and it is the part that gets cut when the sprint is tight.

Styled-but-stale means you inherit the CSS. react-albus was last published in June 2022 and still pulls in three runtime dependencies (history, hoist-non-react-statics, prop-types). A styled component that has stopped shipping is one you restyle with !important, which is the sound of a dependency that has stopped helping.

This is the section worth keeping even if you install nothing.

The mental model: a multi-step form is three independent things wearing one component's clothes.

Everything else is a projection of those three. The progress bar is a projection of the cursor. Persistence is serialising the data. A deep link is the cursor in the URL. Focus management is a side effect of the cursor changing.

The payoff is diagnostic. Every wizard bug now has an address:

Note what the gate is not: it is not a submit handler. It runs on every render, so it must be pure and cheap, and it must never set state. Get that wrong and you have an infinite render loop rather than a validation bug.

The three pieces above are exactly what react-form-wizard-component implements, and v2.0.0 landed on npm at the end of August 2026.

That is a working wizard with a progress bar, arrow-key and Home/End navigation, swipe on touch, focus movement, and live-region announcements.

Honestly, in one sentence: a styled component and a headless hook from the same package — 5.85 kB minified and brotlied, zero runtime dependencies, React 17, 18 and 19. Those size numbers are the ones CI measures with size-limit on every commit, not a bundlephobia guess; the stylesheet is another 1.38 kB.

The example above. Each <FormWizard.TabContent> is a step; title and icon are optional.

Key concept: the children API owns the cursor for you and nothing else. It is the right choice only while every user sees every step.

Key concept: condition is evaluated against shared data, so branching is declarative. You never write steps.filter(...) and then fix the off-by-one in the progress bar.

The contract is deliberately tiny. Return true to allow navigation, a string to block it and supply the message, false to block silently:

Two adapters produce that function from tools you already use. With Zod:

With react-hook-form, gating a step on a subset of one form's fields:

Key concept: this is what "per-step validation" should mean — one form, one schema, and a gate that only looks at its own fields. Not four forms glued together with a reducer.

Neither zod nor react-hook-form becomes a dependency. Both adapters are typed structurally: zodValidator accepts anything with a safeParse method, so Valibot and ArkType work too, and hookFormValidator reads formState.errors and nothing else — it never mutates form state, which is what keeps it safe to run on every render. Combine rules with composeValidators(...); first failure wins.

Key concept: <FormWizard /> is built on this hook. Choosing headless is not choosing a different library — the state machine is identical, you are only declining the markup and the stylesheet.

Here is the part worth knowing if you are already on 1.x.

Every prop, method, hook and adapter is unchanged. v2.0.0 is a major version because the default appearance changed, and a visual change to a component you already styled is a breaking change even when the types say otherwise. Semver's job is to warn you before the deploy, not after.

Keeping the exact v1 look is a two-line diff:

This is the most interesting decision in the release, and it generalises well beyond this package.

v1's stylesheet had no prefers-color-scheme rules at all — dark mode existed only as inline styles you hand-listed through a customDarkModeColor prop. The obvious fix is to add a prefers-color-scheme block. That fix is wrong, and here is why:

So the default (colorScheme="auto") reacts only to explicit signals from the host page: an ancestor carrying [data-theme="dark"] or .dark — which is what Tailwind, next-themes, Docusaurus and Fumadocs all set — or the darkMode prop.

If you own the whole page rather than a component inside someone else's, the media query is the right tool — I wrote about the light-dark() CSS function for exactly that case. The rule of thumb: the page may read the OS; a component should read the page.

v1 set colours as inline styles on the markers, the rail and the footer. Inline styles beat every selector you can write short of !important, which is why theming and dark mode were unreliable. In v2, all of it flows from CSS custom properties and state classes:

Your CSS wins now, with normal specificity. Each step also carries state classes — active, rfw-done, rfw-invalid — so you can style a completed or failed step directly.

And because the v1 skin moved into its own opt-in stylesheet, the default is smaller than 1.2.1 despite gaining a full dark palette: 1.38 kB brotlied, down from 1.85 kB.

A genuine bug, and my favourite kind — the one that only shows up in a real app. showErrorOnTab defaulted to !isValid, so any step carrying a validator painted its marker red on first paint. A wizard whose first question was required looked broken on load: the user is accused before they have typed a character.

The error state now waits until the user has actually tried to leave the step:

An explicit showErrorOnTab still applies immediately.

Keep the bundled skin but adopt your theme — one import, no unstyled, Tailwind v4:

Or build it entirely from utility classes:

One trap worth naming: the preset's classes live in node_modules, and Tailwind only emits classes it can see. Point it at the package or you will get an unstyled wizard and no error message:

Every class in the preset is a literal string for that reason — nothing is built by template concatenation, because `bg-${colour}-600` is invisible to a scanner. The accent reads from bg-[var(--rfw-primary)], so recolouring stays a one-line CSS change instead of a rebuild.

mode: "onChange" matters — the adapter reads formState.errors, so the errors have to be current for the gate to be accurate.

That is the passport-upload bug from the opening, closed. Data goes to web storage, the cursor goes to ?step=, and both are best-effort — private browsing and quota errors are caught, never thrown at the user. Clear it with ref.current.reset().

The rail, the progress bar, and the "is this the last step" logic all recount themselves. There is no index arithmetic anywhere in your code.

The credibility of everything above depends on this section being real.

Give each step a pure predicate over the shared form data that returns true or an error message, and check it before advancing the cursor. Do not create one <form> per step — you lose cross-step values and end up reconciling four states. With this package that predicate is the validate option, and zodValidator / hookFormValidator generate it from a schema or a field subset.

Serialise the shared data object to sessionStorage (clears with the tab) or localStorage (survives a restart) on every change, and restore it on mount. Keep the step index in the URL rather than storage, so a shared link opens the right step. persist={{ key, storage }} and syncToUrl do both; write it yourself in about twenty lines if you prefer.

Yes, but the component holding the cursor must be a client component. This package ships a "use client" directive inside all three bundles, so you can import FormWizard directly from a server component without writing a wrapper. Import the stylesheet once, usually in app/layout.tsx.

Read the page, not the operating system. Look for an ancestor with [data-theme="dark"] or a .dark class — the conventions Tailwind, next-themes, Docusaurus and Fumadocs already set — and expose a prop for hosts that do it differently. Reading prefers-color-scheme inside a component means a light page on a dark-mode machine gets a dark widget on a white background.

Almost never, when hand-rolled. The ARIA tabs pattern wants tablist/tab/tabpanel roles, aria-selected, aria-controls, a roving tabIndex, arrow-key and Home/End handling, focus moved to the revealed panel, and a live region so the change is announced at all. Related reading on the same theme: the inert attribute and what <dialog> gives you for free.

Only if you styled it. The component API is identical — every prop, method, hook and adapter behaves exactly as in 1.2.x. If you never wrote CSS against the wizard, you get the new look and working dark mode with no code change. If you did, variant="legacy" plus the legacy.css import restores v1 pixel for pixel.

Everything you need to build a correct multi-step form, whichever library you use.

The whole pattern, annotated:

That refresh on step four, at the top? persist puts the data back and syncToUrl puts the cursor back, and the user never learns it happened. The rest of the list — the gate, the focus, the announcement, the roving tabindex — is the part that was always going to take a week, whoever writes it.

What's your worst multi-step form story: the one that lost data, or the one nobody could operate with a keyboard?

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: