Component

Wizard

A multi-step flow orchestration component with a visual step rail, controlled navigation, and optional-step skip support — designed for onboarding flows, setup screens, and multi-page forms.

Basic vertical

Default orientation with a vertical step rail on the left. Use Back and Next to move between steps; optional steps show a Skip button.

Region

Content for step 2 goes here.

Horizontal

Pass orientation="horizontal" to render the step rail across the top with the content below.

Goal

Horizontal layout — rail runs across the top.

Controlled

Pass step and onStepChange to manage the current step externally, and onComplete to react to the final action.

Goal

Controlled mode — step 1 of 5.

Installation

$pnpm add @refraction-ui/react

Usage

tsx

import { Wizard } from '@refraction-ui/react'
import type { WizardStep } from '@refraction-ui/react'

const steps: WizardStep[] = [
  { id: 'goal',         label: 'Goal' },
  { id: 'region',       label: 'Region' },
  { id: 'expectations', label: 'Expectations' },
  { id: 'placement',    label: 'Placement', optional: true },
  { id: 'account',      label: 'Account' },
]

export function OnboardingWizard() {
  const [step, setStep] = React.useState(0)

  return (
    <Wizard
      steps={steps}
      step={step}
      onStepChange={setStep}
      onComplete={() => console.log('done!')}
    >
      {(index) => <StepContent stepIndex={index} />}
    </Wizard>
  )
}

Props

Prop	Type	Default	Description
`steps`	`WizardStep[]`	--	Step definitions for the rail. Each step has `id`, `label`, and an optional `optional` flag.
`step`	`number`	--	Controlled current step index (0-based).
`defaultStep`	`number`	`0`	Initial step index for uncontrolled usage.
`onStepChange`	`(index: number) => void`	--	Called when the current step changes via Back or Next.
`onComplete`	`() => void`	--	Called when the user activates the action on the final step.
`orientation`	`'vertical' \| 'horizontal'`	`'vertical'`	Orientation of the step rail.
`nextLabel`	`React.ReactNode`	`'Next'`	Label for the Next button.
`backLabel`	`React.ReactNode`	`'Back'`	Label for the Back button.
`completeLabel`	`React.ReactNode`	`'Complete'`	Label for the primary action on the final step.
`skipLabel`	`React.ReactNode`	`'Skip'`	Label for the Skip button, shown only on optional steps.
`children`	`React.ReactNode \| ((currentIndex: number) => React.ReactNode)`	--	Step content. Pass a render prop `(index) => …` to render different content per step.
`className`	`string`	--	Additional CSS classes to apply to the root element.