Add this component

npx zentauri-ui add wizard

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

Check Installation for shared peers. This component keeps styling in Tailwind classes and the --zui-* token contract.

Form

Wizard multi-step forms

Wizard is a compound component for building multi-step workflows with headers, progress indicators, navigation controls, sidebars, and footers — all declaratively composed.

Step 1 of 0

Examples

The Wizard component provides a multi-step workflow with compound sub-components for headers, progress indicators, navigation, sidebars, and footers.

Basic wizard

A simple multi-step form with header, dots progress, and navigation.

Step 1 of 0

With sidebar

Display all steps in a sidebar with clickable navigation.

Step 1 of 0

Custom footer

Wrap the navigation in a custom footer layout.

Wizard API

Generated from the package prop types and variant definitions.

Wizard

WizardProps

Variants

Prop	Type	Default
appearance	`aquabluecardcrimsoncyandefaultelectricemeraldforestghostgradient-bluegradient-green`+32	default
size	`lgmdsm`	md

Behavior

Prop	Type	Default
defaultStep	`number \| undefined`	none
linear	`boolean \| undefined`	none
onCancel	`(() => void) \| undefined`	none
onFinish	`(() => void) \| undefined`	none
onReset	`(() => void) \| undefined`	none
onStepChange	`((step: number) => void) \| undefined`	none
onStepComplete	`((stepId: string) => void) \| undefined`	none
persist	`boolean \| undefined`	none
storageKey	`string \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

WizardContent

WizardContentProps

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

WizardFooter

WizardFooterProps

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

WizardHeader

WizardHeaderProps

Variants

Prop	Type	Default
size	`lgmdsm`	md

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

WizardNavigation

WizardNavigationProps

Variants

Prop	Type	Default
size	`lgmdsm`	md

Behavior

Prop	Type	Default
backLabel	`ReactNode`	none
cancelLabel	`ReactNode`	none
finishLabel	`ReactNode`	none
nextLabel	`ReactNode`	none
showCancel	`boolean \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

WizardProgress

WizardProgressProps

Behavior

Prop	Type	Default
variant	`WizardProgressVariant \| undefined`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

WizardSidebar

WizardSidebarProps

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

WizardStep

WizardStepProps

Behavior

Prop	Type	Default
description	`string \| undefined`	none
disabled	`boolean \| undefined`	none
hidden	`boolean \| undefined`	none
icon	`ReactNode`	none
optional	`boolean \| undefined`	none
title*	`string`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
id*	`string`	none

WizardAnimated

WizardAnimatedProps

animated

Behavior

Prop	Type	Default
appearance	'default' \| 'outline' \| 'ghost' \| 'card' \| 'separated' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gradient-orange' \| null \| undefined	none
defaultStep	`number \| undefined`	none
linear	`boolean \| undefined`	none
onCancel	`(() => void) \| undefined`	none
onFinish	`(() => void) \| undefined`	none
onReset	`(() => void) \| undefined`	none
onStepChange	`((step: number) => void) \| undefined`	none
onStepComplete	`((stepId: string) => void) \| undefined`	none
persist	`boolean \| undefined`	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none
storageKey	`string \| undefined`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

WizardContentAnimated

WizardContentAnimatedProps

animated

Behavior

Prop	Type	Default
animation	`WizardAnimation \| undefined`	none

Inherited HTML props

Prop	Type	Default
children	`ReactNode`	none
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

Overview

Wizard is a compound component that provides a complete multi-step workflow solution without boilerplate. Compose WizardStep children inside a Wizard parent, then add optional sub-components like WizardHeader for step indication, WizardProgress for visual progress (bar, dots, or numbers), WizardNavigation for built-in back/next/finish buttons, WizardSidebar for a step list, and WizardFooter for custom footer layouts.

Common use cases

Checkout and payment flows.
Multi-page registration and signup forms.
Onboarding wizards with sidebar navigation.
Survey and questionnaire interfaces.

FAQ

Can I control the current step from outside?

The Wizard is uncontrolled by default. Use the useWizard hook inside the Wizard to access currentStep, next, previous, goTo, reset, and other controls. For fully controlled state, the wizard accepts defaultStep and onStepChange.

How do I skip certain steps conditionally?

Set the hidden prop on Wizard.Step to conditionally hide steps. Hidden steps are automatically excluded from navigation and progress calculations.

Can I persist the wizard state across page reloads?

Yes. Set persist and storageKey on the Wizard component to save the current step and completed steps to localStorage.

How do I add animations between steps?

Import from the animated entry: @zentauri-ui/zentauri-components/ui/wizard/animated. Use WizardContentAnimated with the animation prop (slide, fade, scale, flip).