Wizard

View in Storybook

Explore interactive examples and all component variations in our Storybook.

The WizardProgress component provides a step-by-step navigation interface for multi-step workflows. It renders a visual progress bar with labeled steps, handles completed/active/disabled states, and optionally displays each step's content inline. Combine it with the useWizard hook for full navigation control.

Basic Usage

View in Storybook

Account

Company

Payment

Done

Step 1 — Account Information

Enter your name and email address.

With a Form

Embed form fields inside each step's children so the content updates as the user progresses.

Create Account

Profile

Security

Done

Full Name

Email

Free Navigation

Set freeNavigation to allow clicking any step directly, not only completed ones. Useful for settings wizards where users can jump between steps freely.

General

Notifications

Privacy

Documents

General Settings

Configure general application settings.

Without Labels

Set showLabels={false} for a compact progress bar that shows only icons — useful in narrow layouts or mobile views.

Account Information

With Disabled Steps

Mark individual steps as disabled to prevent navigation to them. The useWizard hook also accepts a disabled array of 1-based step numbers to skip during sequential navigation.

Account

Review

Payment

Done

Account Information

Step 3 (Payment) is disabled in this example.

Properties

WizardProgress

Property	Type	Default	Description
children	ReactNode	—	One or more WizardProgressStep elements.
currentStep	number	—	1-based index of the active step.
onGoToStep	(step: number) => void	—	Callback fired when a navigable step is clicked. Required for click navigation.
freeNavigation	boolean	false	When true, all non-disabled steps are clickable regardless of completion state.
showLabels	boolean	true	Show or hide the text label below each step icon.
className	string	—	Additional CSS classes for the root element.

WizardProgressStep

Property	Type	Default	Description
label	string	—	Text label shown below the step icon and used as aria-label.
icon	ComponentType<{ className?: string }>	—	Icon component rendered inside the step circle.
disabled	boolean	false	Marks the step as unreachable. Renders at reduced opacity.
children	ReactNode	—	Content displayed when this step is active.

useWizard Hook

A convenience hook for managing wizard navigation state.

import { useWizard } from "buildgrid-ui";

const { currentStep, goNext, goPrevious, goToStep, canGoNext, canGoPrevious } = useWizard({
  totalSteps: 4,
  disabled: [3],  // 1-based step numbers to skip
  initial: 1,     // starting step (default: 1)
});

Options

Option	Type	Default	Description
totalSteps	number	—	Total number of steps in the wizard.
disabled	number[]	[]	1-based step numbers that are skipped during goNext / goPrevious.
initial	number	1	The step to start on.

Return Values

Value	Type	Description
currentStep	number	The current active step (1-based).
goNext	() => void	Advance to the next non-disabled step.
goPrevious	() => void	Go back to the previous non-disabled step.
goToStep	(step: number) => void	Jump to a specific step directly.
canGoNext	boolean	Whether there is a next non-disabled step.
canGoPrevious	boolean	Whether there is a previous non-disabled step.

Accessibility

• Each step button has an aria-label equal to its label prop and a title tooltip.
• Disabled steps set aria-disabled and visually render at 40% opacity.
• Completed steps that allow back-navigation are fully keyboard-accessible via the step buttons.
• The active step button does not trigger navigation (already current).

Common Use Cases

• Onboarding flows — guide new users through account setup step by step
• Multi-step forms — break long forms into digestible pages
• Checkout processes — cart → shipping → payment → confirmation
• Configuration wizards — structured setup with optional sections
• Progress tracking — visual indication of where the user is in a long process