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).

---

🚀 Quick Start (v2.0.0 Modern)

Version 2.0.0 introduces the Factory Pattern, providing 100% type safety and optimized performance out of the box.

$3

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();
`

$3

`tsx
import { WizardProvider } from './wizards/auth-wizard';

const App = () => (



);
`

$3

`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)} />;
};
`

---

✨ Key Features

- 🧠 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.

---

🏗️ Core Concepts

$3

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 };
`

$3

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.

---

💾 State Persistence

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'
}
};
`

---

🛠️ Performance Tuning

| 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 |

---

⚠️ Legacy Support (v1.x)

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.

---

📄 Documentation & Demos

- 📚 Full Docs: Interactive Documentation Portal
- 🧪 Enterprise Demo: Google-quality complex wizard implementation
- 🚀 NPMS: View on npm

---

License

MIT © ZizzX