A flexible, headless, and strictly typed multi-step wizard library for React.
npm install wizzard-stepper-react


A flexible, headless, and strictly typed multi-step wizard library for React. Built with adapter patterns in mind to support any form library (React Hook Form, Formik, etc.) and any validation schema (Zod, Yup).
---
Version 2.0.0 introduces the Factory Pattern, providing 100% type safety and optimized performance out of the box.
Define your data schema and generate typed hooks.
``typescript
// wizards/auth-wizard.ts
import { createWizardFactory } from 'wizzard-stepper-react';
interface AuthSchema {
email: string;
preferences: { theme: 'light' | 'dark' };
}
export const {
WizardProvider,
useWizard,
useWizardValue,
useWizardActions
} = createWizardFactory
`
`tsx
import { WizardProvider } from './wizards/auth-wizard';
const App = () => (
);
`
`tsx
import { useWizardValue, useWizardActions } from './wizards/auth-wizard';
const EmailInput = () => {
// โก Atomic re-render: component only updates if 'email' changes
const email = useWizardValue('email');
const { setData } = useWizardActions();
return setData('email', e.target.value)} />;
};
`
---
- ๐ง Headless Architecture: Full control over UI. You bring the components, we provide the logic.
- ๐
Modern First: Optimized for React 18 with selective rendering and external state store.
- ๐ Adapter Pattern: Zero-dependency adapters for Zod, Yup validation.
- ๐๏ธ Complex Data: Built-in support for nested objects using dot notation (user.address.zip).
- ๐พ Advanced Persistence: Auto-save to LocalStorage, SessionStorage, or Custom API adapters.
- ๐ ๏ธ Developer Tools: High-performance debugging overlay and Redux DevTools integration.
---
We are library-agnostic. Use our pre-built adapters or write your own.
`tsx
import { ZodAdapter } from 'wizzard-stepper-react';
import { z } from 'zod';
const schema = z.object({ age: z.number().min(18) });
const adapter = new ZodAdapter(schema);
// In your config:
const step = { id: 'age', validationAdapter: adapter };
`
1. Validation: Current step is checked. Navigation stops if invalid.
2. Resolution: Next step conditions (dynamic branching) are evaluated.
3. Guards: beforeLeave hooks run (e.g., for "Unsaved Changes" modals).
4. Commit: State updates and navigation completes.
---
Isolate your wizard data to prevent collisions when using multiple instances.
`typescript
import { LocalStorageAdapter } from 'wizzard-stepper-react';
const config = {
persistence: {
// ๐ก๏ธ Always use a unique prefix for isolation
adapter: new LocalStorageAdapter('auth_wizard_v2'),
mode: 'onStepChange'
}
};
`
---
| Hook | Returns | Re-renders | Best For |
| :--- | :--- | :--- | :--- |
| useWizardActions | Navigation/Setters | Zero | Buttons, Handlers |useWizardValue
| | Specific Field | Atomic | Inputs, Labels |useWizardState
| | UI Meta (Progress) | Minimal | Progress Bars |useWizard
| | Everything | Full | Orchestration |
---
If you are maintaining an older project, you can still use the classic Context-based provider. Note that this mode does not support the new performance-optimized hooks.
`tsx
import { WizardProvider, useWizard } from 'wizzard-stepper-react';
const OldApp = () => (
);
``
For migration steps, see MIGRATION.md.
---
- ๐ Full Docs: Interactive Documentation Portal
- ๐งช Enterprise Demo: Google-quality complex wizard implementation
- ๐ NPMS: View on npm
---
MIT ยฉ ZizzX