React Wizard Control


A production-grade, fully customisable wizard/stepper component for React 19+ and TypeScript 5+. Designed for complex workflows with built-in support for VS Code extensions, theming, validation, and accessibility.

Features

- Type-safe: comprehensive TypeScript 5+ definitions
- Fully customisable: theme system with VS Code integration
- Accessible: keyboard navigation and ARIA-friendly components
- Framework-agnostic: suitable for web apps and VS Code webviews
- Dual format: ESM and CommonJS builds
- State persistence: optional localStorage integration
- Performant: optimised hook-based architecture

Installation

``bash
npm install @neuralsea/react-wizard


or

`tsx
import { Wizard } from '@neuralsea/react-wizard';
import type { StepComponentProps, WizardStep } from '@neuralsea/react-wizard';
import '@neuralsea/react-wizard/styles';

type WizardData = {
name?: string;
newsletter?: boolean;
};

const PersonalInfoStep: React.FC> = ({
data,
updateData,
}) => (


export function App() {
return (
steps={steps}
onComplete={(data) => {
console.log('Wizard completed with data:', data);
}}
/>
);
}
`

Core concepts

$3

Each step is defined by WizardStep:

`ts
interface WizardStep {
id: string;
title: string;
description?: string;
component: ComponentType;
validate?: () =>
| boolean
| { valid: boolean; error?: string }
| Promise;
canSkip?: boolean;
icon?: ComponentType<{ size?: number }>;
optional?: boolean;
}
`

$3

Step components receive these props:

`ts
interface StepComponentProps {
data: TData;
updateData: (updates: Partial) => void | Promise;
goToStep: (stepId: string) => void;
goNext?: () => Promise;
goPrevious?: () => void;
}
`

Theming

$3

`tsx
steps={steps}
theme={{
primary: '#3b82f6',
primaryHover: '#2563eb',
success: '#10b981',
error: '#ef4444',
radius: '0.5rem',
}}
/>
`

$3

For VS Code extensions:

`tsx
import { vscodeTheme } from '@neuralsea/react-wizard';

;
`

Advanced usage

$3

Take full control of layout:

`tsx
import {
Wizard,
StepIndicator,
StepContent,
Navigation,
} from '@neuralsea/react-wizard';

export function CustomWizard() {
return (



`tsx
import { useWizard } from '@neuralsea/react-wizard';

type WizardData = { name: string };

export function CustomComponent() {
const { steps, currentStepIndex, data, goNext, isLastStep } =
useWizard();

return (


`tsx
import { withWizardStep, withValidation } from '@neuralsea/react-wizard';
import type { StepComponentProps, ValidationResult } from '@neuralsea/react-wizard';

interface MyData {
email: string;
}

const MyStep: React.FC> = ({ data, updateData }) => (
void updateData({ email: e.target.value })} />
);

const validate = (data: MyData): ValidationResult =>
data.email.includes('@') ? { valid: true } : { valid: false, error: 'Invalid email' };

export default withValidation(withWizardStep(MyStep), validate);
`

$3

Validation supports booleans or structured error messages:

`tsx
const steps: WizardStep[] = [
{
id: 'email',
title: 'Email',
component: EmailStep,
validate: () => {
if (!data.email) return { valid: false, error: 'Email is required' };
if (!data.email.includes('@')) return { valid: false, error: 'Invalid email format' };
return { valid: true };
},
},
];
`

$3

`tsx
steps={steps}
persistData
storageKey="my-wizard-data"
onComplete={(data) => {
localStorage.removeItem('my-wizard-data');
}}
/>;
`

$3

Enabled by default:

- Alt + Right Arrow: next step
- Alt + Left Arrow: previous step

Disable keyboard navigation:

`tsx

`

Accessibility

The wizard supports:

- ARIA labels and roles
- Keyboard navigation
- Screen reader-friendly structure
- Reduced motion preferences

Licence

MIT. See LICENSE`.