Migration

From 1.2.x → 2.0.0

The API did not change. Every prop, method, hook and adapter behaves as it did in 1.2.x. What changed is how the wizard looks and how it applies colour.

If you never styled the wizard, upgrade and you are done — you get the new look and dark mode that actually works.

Keeping the old appearance

Two lines:

  import "react-form-wizard-component/styles.css";
+ import "react-form-wizard-component/legacy.css";

- <FormWizard schema={schema} />
+ <FormWizard variant="legacy" schema={schema} />

The v1 stylesheet is shipped separately, so sites on the new default do not download it.

If you wrote CSS against the wizard

v1 painted colours as inline styles on the markers, rail and footer, so any rule you wrote had to fight them — usually with !important. The modern skin paints nothing inline; styling flows from custom properties and state classes.

That means your overrides may now apply more than you expect, and any !important you added to beat the old inline styles is probably no longer needed.

- .react-form-wizard .wizard-icon-circle { background: #111 !important; }
+ .react-form-wizard { --rfw-primary: #111; }

Behaviour worth knowing

• Steps no longer turn red on load. showErrorOnTab used to default to !isValid, so any step with a validator rendered in the error colour before the user had done anything. It now waits until they try to leave the step. Pass showErrorOnTab explicitly for the old behaviour.
• Dark mode follows the page, not the OS. An ancestor with .dark or [data-theme="dark"], or the darkMode prop. Add colorScheme="system" if your app themes purely from prefers-color-scheme.
• color still works, but it is an inline style and therefore beats your CSS. Prefer theme={{ primaryColor }}, which sets --rfw-primary.

New in 2.0

• variant — "modern" (default) or "legacy"
• colorScheme — "auto" (default), "system", "light", "dark"
• classNames.stepComplete and classNames.stepInvalid
• Tailwind integration: a token bridge and tailwindPreset()

From 1.1.x → 1.2.0

No breaking changes. The children API, the schema API and every existing prop behave as before. Upgrade and nothing needs touching.

Optional cleanups:

- import "react-form-wizard-component/dist/style.css";
+ import "react-form-wizard-component/styles.css";

  // Next.js App Router — the directive is now in the published bundle
- "use client";
  import FormWizard from "react-form-wizard-component";

Things that were broken and now are not

If you worked around any of these, you can remove the workaround:

Small behaviour changes

• onTabChange no longer fires on mount. It previously reported a 0 → 0 transition on the first render. If you relied on that to initialise something, do it directly instead.
• An out-of-range startIndex is clamped on the first render rather than briefly rendering an empty panel.

From 0.2.7 → 1.2.0

If you pinned 0.2.7 because v1 required React 19 — you can upgrade now. React 18 (and 17) support was restored in 1.2.0. The incompatibility was a build-configuration bug, not a limitation of the component.

Two API changes carried over from 1.0.0:

- const handleComplete = () => {};
+ const handleComplete = (data?: WizardData) => {};

- const handleTabChange = ({ prevIndex, nextIndex }) => {};
+ const handleTabChange = ({ prevIndex, nextIndex, stepId }) => {};

Everything else in the children API is unchanged. What you gain:

• Schema API with conditional steps
• Validation adapters for Zod and react-hook-form
• Headless useWizard()
• Theming and unstyled mode
• Persistence and URL sync
• Accessibility — ARIA, live regions, keyboard
• Correct TypeScript types, working require(), and "use client"

From 1.0.0 / 1.1.x on React 19

Nothing to do. React 19 remains fully supported and is covered by CI alongside 17 and 18.

Checking your upgrade

npm install react-form-wizard-component@latest
npx tsc --noEmit   # types now resolve — this used to fail

If something regressed, please open an issue with your React version and bundler.