react-wizard-engine

Multi-step flow engine for React. Steps, categories, branches. Pluggable strategies, listeners, initializers. Resolver hooks. Async navigation with cancellation. Headless core plus an opinionated Radix + Tailwind styled adapter.

Live demo: react-wizard-engine.vercel.app — 5 routes covering basic setup, every-option-preset, custom initializer, plain linear, and branch fork (diamond).

Install

pnpm add react-wizard-engine lucide-react @radix-ui/react-slot
# only if you also use the styled /shadcn adapter:
pnpm add @radix-ui/react-dialog

Quickstart

import {
  WizardProvider,
  WizardCategory,
  WizardStep,
  WizardBack,
  WizardNext,
} from 'react-wizard-engine';

const initial = [
  { id: 'name',  categoryId: 'profile', htmlIndex: 0, branches: ['main'], isActive: true,  isShow: true, isCompleted: false, isSkipped: false },
  { id: 'email', categoryId: 'profile', htmlIndex: 1, branches: ['main'], isActive: false, isShow: true, isCompleted: false, isSkipped: false },
  { id: 'done',  categoryId: 'confirm', htmlIndex: 2, branches: ['main'], isActive: false, isShow: true, isCompleted: false, isSkipped: false },
];

export function SignupWizard() {
  return (
    <WizardProvider state={initial}>
      <WizardCategory categoryId="profile">
        <WizardStep id="name">...name form...</WizardStep>
        <WizardStep id="email">...email form...</WizardStep>
      </WizardCategory>
      <WizardCategory categoryId="confirm">
        <WizardStep id="done">...review...</WizardStep>
      </WizardCategory>
      <WizardBack />
      <WizardNext />
    </WizardProvider>
  );
}

Runnable Vite example: examples/basic/ — 5 routes (setup, setup-full, setup-initializer, linear, diamond). pnpm install && pnpm dev.

Styled adapter

The /shadcn subpath ships an opinionated styled WizardTopBar and WizardLayout built on Radix + Tailwind utility classes that match shadcn defaults.

import { WizardLayout, WizardTopBar, WizardComponentsProviderWithDefaults } from 'react-wizard-engine/shadcn';

<WizardComponentsProviderWithDefaults>
  <WizardProvider state={initial}>
    <WizardLayout
      topBar={<WizardTopBar onClose={onClose} />}
      rail={<MyRail />}
    >
      {/* steps */}
    </WizardLayout>
  </WizardProvider>
</WizardComponentsProviderWithDefaults>

To use your own button:

import { WizardComponentsProvider } from 'react-wizard-engine';
import { Button } from '@/components/ui/button';

<WizardComponentsProvider Button={Button}>
  <WizardProvider state={initial}>{}</WizardProvider>
</WizardComponentsProvider>

Concepts

• Step — one screen the user sees. id, categoryId, htmlIndex (declaration order), branches[], plus four flags (isActive/isShow/isCompleted/isSkipped).
• Category — a group of steps sharing a header tab.
• Branch — a named path through categories.

See src/core/ for full type definitions.

Hooks

• useWizard() — engine: next, back, go, showStep, hideStep, goToCategory, nextCategory, backCategory, skipCategory, resetWizard, exitWizard, completeWizard, snapshot fields tree / steps / lastActiveStep / shapeId. All control methods return Promise<boolean>.
• useWizardStep(id) — subscribes to one step's slice; re-renders only when its flags flip.
• useWizardEvent('*' | type, handler) — subscribes to engine events.

Strategies (pluggable)

Compose providers to override strategies/config. Back, visibility, progress, and scroll strategies are all overridable. See src/core/strategies/.

composeWizardProviders(
  withConfig({ isBackResetCompleted: false }),
  withScrollStrategy(new WizardSmoothScrollStrategy()),
)

Available helpers: withConfig, withInitializer, withListener, withProgressStrategy, withScrollContainer, withScrollStrategy, withVisibilityStrategy.

License

MIT (c) Nazarii Kovtun