React Form Wizard

Quick Start

Accessible multi-step form wizard for React 17, 18 and 19 — zero dependencies, styled or headless.

Quick Start

An accessible multi-step form wizard for React, with validation, a progress bar and no runtime dependencies. It ships a styled component and a headless hook from the same package.

Install

npm install react-form-wizard-component

Full setup notes live in Installation and Framework setup.

yarn add react-form-wizard-component

Works with React 17, 18 and 19.

You can upgrade now. React 18 support was restored in v1.2.0 — the incompatibility was a build-configuration bug (React's JSX runtime was being compiled into the bundle), not a limitation of the component. See Migration.

Usage

import FormWizard from "react-form-wizard-component";
import "react-form-wizard-component/styles.css";

function App() {
  const handleComplete = () => {
    console.log("Form completed!");
  };

  const tabChanged = ({
    prevIndex,
    nextIndex,
  }: {
    prevIndex: number;
    nextIndex: number;
  }) => {
    console.log("prevIndex", prevIndex);
    console.log("nextIndex", nextIndex);
  };

  return (
    <>
      <FormWizard
        shape="circle"
        color="#e74c3c"
        onComplete={handleComplete}
        onTabChange={tabChanged}
      >
        <FormWizard.TabContent title="Personal details" icon="ti-user">
          {/* Add your form inputs and components for the first step */}
          <h1>First Tab</h1>
          <p>Some content for the first tab</p>
        </FormWizard.TabContent>
        <FormWizard.TabContent title="Additional Info" icon="ti-settings">
          <h1>Second Tab</h1>
          <p>Some content for the second tab</p>
        </FormWizard.TabContent>
        <FormWizard.TabContent title="Last step" icon="ti-check">
          <h1>Last Tab</h1>
          <p>Some content for the last tab</p>
        </FormWizard.TabContent>
      </FormWizard>
      {/* the icons above come from Themify */}
      <style>{`
        @import url("https://cdn.jsdelivr.net/gh/lykmapipo/themify-icons@0.1.2/css/themify-icons.css");
      `}</style>
    </>
  );
}

export default App;

That is a working three-step wizard with a progress bar, keyboard navigation, swipe support and screen-reader announcements.

react-form-wizard-component/styles.css was added in v1.2.0. The older react-form-wizard-component/dist/style.css still resolves, so existing imports keep working.

Next.js

The published bundles carry a "use client" directive, so importing the component from a server component works with no wrapper. You no longer need to add "use client" yourself.

// app/signup/page.tsx — a server component
import FormWizard from "react-form-wizard-component";
import "react-form-wizard-component/styles.css";

export default function Page() {
  return (
    <FormWizard title="Signup">
      <FormWizard.TabContent title="Account">…</FormWizard.TabContent>
      <FormWizard.TabContent title="Review">…</FormWizard.TabContent>
    </FormWizard>
  );
}

Import the stylesheet once, anywhere in the tree — commonly app/layout.tsx.

New in v2

The default appearance was redesigned, and dark mode now works without configuration. The v1 look is still available:

import "react-form-wizard-component/legacy.css";
<FormWizard variant="legacy" />

Nothing else changed — see Migration.

What else is in the box

Schema APIDeclarative steps with conditional visibility and per-step validation.
Validation adaptersZod and react-hook-form integration, still zero dependencies.
Headless useWizard()The same state machine with none of the markup.
ThemingCSS custom properties, automatic dark mode, or go fully unstyled.
TailwindAdopt your Tailwind theme with one import, or build it from utility classes.
PersistenceSurvive a reload; mirror the active step into the URL.
AccessibilityARIA roles, live-region announcements, focus management, full keyboard operation.

Compatibility

ReactSupportedNotes
19.x
18.x
17.xThrough any bundler (Vite, webpack, Next.js, CRA). Not loadable under native Node ESM — React 17 ships no exports field, so Node cannot resolve react/jsx-runtime. That is a React 17 limitation, not this package's.
16.x⚠️Untested. Requires react/jsx-runtime, so React 16.14+.
EnvironmentSupported
ESM import
CommonJS require()
TypeScript — bundler, node16, node10✅ verified with attw
Next.js App Router / RSC"use client" included
Server-side rendering
UMD via CDN✅ unpkg / jsDelivr

Props

See Props for the full FormWizard reference, and FormWizard.TabContent for step props.

Examples

Complete builds you can lift straight into a project:

Feature demos, one capability at a time:

License

MIT. See LICENSE.

On this page