Implementing Multi Step Wizard

The useState Trap and Scattered Validation Logic

We've all seen the code. You open a component file for a "simple" multi-step wizard, and you're hit with a wall of useState hooks. There's a step variable tracking navigation, a separate errors object for validation, and a useEffect that fires every time step changes to reset or persist form data. By the time you reach the validation logic, it's scattered across three different functions and a dozen inline checks.

This is the anti-pattern that kills productivity. Building a multi-step wizard isn't just about hiding and showing divs. It's about managing complex state transitions, gating navigation based on validation results, handling cross-step dependencies, and ensuring the interface is accessible to screen readers and keyboard users. When you hack this together with local state, you end up with race conditions where the form submits before validation finishes, or data is lost when the user hits the browser's back button.

If you're currently wrestling with this, you're not alone. Most engineers try to bolt on validation later, leading to a disconnect between the UI state and the form schema. We built this skill so you don't have to. It provides a structured approach to wizard implementation that integrates seamlessly with industry-standard tools like React Hook Form and Zod. For teams that need a broader context, this pattern is the backbone of any complex User Onboarding Flow, where guiding the user through sequential decisions is critical for completion rates.

The core issue is that most wizards lack a clear separation of concerns. The navigation logic is coupled with the UI, the validation is coupled with the submission, and the state is coupled with the DOM. This makes it nearly impossible to add conditional steps or cross-step validation without rewriting half the component. You need a system where the wizard shell handles the flow, the form library handles the data, and the validation layer handles the rules. Without this separation, you're spending weeks maintaining a wizard that should have taken days to build.

Why "Just Use a Library" Breaks Your Architecture

You might think the solution is to grab a wizard library from npm and call it a day. But most wizard libraries are either too opinionated or too fragile. They often bundle their own state management, which conflicts with your app's global store or your preferred form library. Or worse, they're just UI wrappers that don't handle state persistence, leaving you to implement the hard parts anyway.

The cost of this friction is real. Every hour you spend debugging a library's navigation bug is an hour you're not shipping features. More importantly, bad wizard UX directly impacts conversion. If a user can't navigate back to fix a mistake, or if the progress indicator lies about their completion status, they abandon the flow. In a checkout or onboarding context, this translates directly to lost revenue.

Consider the validation layer. A wizard isn't just a sequence of forms; it's a state machine where each step has preconditions. If you're building a Form Builder Pack or a complex configuration tool, your validation needs to be schema-driven and composable. Using a library that doesn't support cross-step validation means you're writing custom logic for every edge case. This bloats your codebase and introduces bugs. We've seen teams spend weeks building custom validation gate logic that should have been handled by a robust Form Validation System integrated with a proper wizard shell.

The financial impact extends beyond development time. Poorly implemented wizards lead to support tickets, user frustration, and lower completion rates. If your wizard is used in a settings page, a broken flow can lock users out of critical configurations. The cost of fixing these issues post-launch is exponentially higher than building it right the first time. You need a solution that treats the wizard as a serious stateful component, not a collection of buttons and forms.

A 5-Step Configuration Flow That Collapsed

Imagine a team building a configuration wizard for an enterprise SaaS product. The flow has five steps: Account Setup, Team Details, Billing, Preferences, and Review. The requirements are straightforward: users can navigate forward and backward, steps can be skipped based on previous answers, and validation must prevent navigation until the current step is complete.

The team started with a basic state machine approach, tracking steps with a simple integer. They used react-hook-form for form management. Everything seemed fine until they hit Step 3. Step 3 is conditional; it only appears if the user selected "Enterprise" in Step 1. Worse, Step 4 requires data from both Step 1 and Step 2. The validation logic became a mess of if/else statements checking step === 3 and step === 4.

Then came the navigation bug. When a user clicked "Back" from Step 4, the form data from Step 3 was lost because the component unmounted and remounted. The team tried to fix this with keepMounted props, but that introduced memory leaks. They also realized that the progress bar was misleading; it showed 5/5 steps, but Step 3 was hidden for 80% of users. Accessibility was an afterthought, and keyboard users got trapped in the hidden steps.

This is a common failure mode. The team was trying to manage state, UI, and validation all in one place. They needed a headless approach where the wizard component manages the state and navigation, but leaves the UI flexible. Libraries like react-multistep offer this headless flexibility, allowing you to control the UI while the component manages the logic ^[1]. However, even with a headless library, you need a clear strategy for validation and accessibility.

The turning point came when they adopted a state machine pattern for the wizard flow. Each step became a state, and transitions were guarded by validation rules. This allowed them to define cross-step dependencies cleanly. For example, Step 4 could only be reached if Step 1 and Step 2 were valid. The wizard library handled the transitions, but the validation was driven by Zod schemas, ensuring type safety and consistency ^[6].

They also integrated a dedicated wizard navigation library to handle the step lifecycle. This separated the concerns: the wizard library managed previousStep, nextStep, and currentStep, while the form library managed the data. This reduced the component complexity by half. The team also added ARIA roles for progress tracking and keyboard navigation, ensuring the wizard was accessible ^[8].

The final result was a wizard that was easy to extend. Adding a new step meant adding a new schema and a new component, not rewriting the navigation logic. The conditional steps worked seamlessly, and the validation was robust. This approach mirrors the principles used in WizardForm, which separates flow orchestration from form validation, allowing you to pair it with your preferred validation library ^[4].

What Changes When You Lock the Wizard Pattern

Once you install this skill and apply the pattern, the complexity collapses. You no longer have to worry about wiring up navigation to validation or managing state persistence. The skill provides a production-grade wizard shell that integrates react-hook-form, react-use-wizard, and Zod validation out of the box.

Your wizards become composable. Each step is a self-contained component with its own schema and validation rules. The wizard shell handles the transitions, ensuring that users can't proceed until the current step is valid. Cross-step validation is handled by a helper function that aggregates schemas from all steps, ensuring data consistency across the flow.

Accessibility is built-in. The wizard shell includes ARIA progress tracking and keyboard navigation support, ensuring that your wizards are usable by everyone. This is critical for compliance and user satisfaction. If you're building a Settings Preferences Page with multiple tabs, this pattern ensures that users can navigate efficiently without getting lost.

You also gain flexibility. The wizard is headless by design, meaning you control the UI. You can style it to match your brand, add animations, or integrate with your design system. The state management is decoupled from the UI, making it easy to test and maintain. This is especially useful for complex flows like Internationalization setups, where you might need to handle language selection across multiple steps.

The skill includes a worked example of a 3-step checkout flow, demonstrating how to implement conditional logic, review steps, and state persistence. This example serves as a template for your own flows, saving you weeks of development time. You can adapt it for onboarding, configuration, or any multi-step process.

What's in the Pack

This skill is a complete toolkit for building multi-step wizards. It includes the orchestrator guide, production templates, validation utilities, API references, and automated checks.

• skill.md — Orchestrator guide defining architecture, state management strategy, validation gating, and file usage instructions for multi-step wizards.
• templates/WizardRoot.tsx — Production-grade wizard shell integrating react-hook-form context, react-use-wizard navigation, ARIA progress tracking, and cross-step validation gating.
• templates/StepComponents.tsx — Reusable step container and controlled input component leveraging useFormContext and useController for prop-less form field management.
• templates/validation.ts — Zod schemas for step-level validation and cross-step validation helper function with TypeScript type inference.
• references/rhf-form-management.md — Canonical react-hook-form API reference covering useForm, FormProvider/useFormContext, useController, getFieldState, and useFormState with production examples.
• references/react-use-wizard-navigation.md — Canonical react-use-wizard API reference covering previousStep, goToStep, stepCount, dynamic step rendering, and handleStep lifecycle.
• references/accessibility-focus-management.md — Authoritative guide on ARIA roles, keyboard navigation, focus trapping, and screen reader announcements specific to wizard interfaces.
• scripts/validate-wizard.sh — Executable shell script that scaffolds structure checks and delegates to the Node validator for programmatic verification.
• validators/check-structure.mjs — Programmatic validator that verifies template file existence, size, and required imports; exits non-zero on structural failure.
• examples/checkout-wizard.tsx — Worked example implementing a 3-step checkout flow with conditional logic, review step, and complete state persistence pattern.

Install and Ship

Stop hacking state. Start shipping wizards.

Upgrade to Pro to install the Multi-Step Wizard skill and transform your complex flows into maintainable, accessible, and high-converting interfaces. The skill is ready to use. Just install it and follow the guide.

Your next wizard should be the last one you build from scratch.

---