Skip to content
Product block

Guided Setup Wizard

A choice-driven wizard with a persistent side rail, real radio groups in a fieldset so arrow keys work, and visited steps navigable while steps ahead stay out of the tab order.

265 lineslucide-reactAdded 8 Aug 2026Updated 10 Sept 2026
  • onboarding
  • wizard
  • setup
  • steps
  • radio

What's included

  • components/setup-wizard.tsx
  • Needs lucide-react

Works with

  • React
  • Next.js
  • Tailwind CSS
  • TypeScript

npx hoverlab add setup-wizard

Or over MCP, from your editor's agent — no account needed.

License

Free to read, copy and install, for personal and non-commercial projects. Shipping it in client work or a paid product needs Pro ($79 once). The source lands in your repo and stops being ours — no attribution, nothing to upgrade.

Was this useful?

Start a page with this section — add more, order them, and leave with the page source.

Preview

Acme
  1. 1Framework
  2. 2Styling
  3. 3Team
What are you building with?

Rendered live in your current theme — this is the same component whose source is below, not a screenshot of it.

Source

components/setup-wizard.tsx
'use client'

/**
 * <SetupWizard> — a full-screen guided setup with a side rail.
 *
 * Where <MultiStepForm> collects data, this one makes *choices*: pick a
 * framework, pick a plan, pick what to import. That difference drives the
 * layout — the rail stays visible the whole time so someone four steps in
 * can still see what they picked and what is left, which a horizontal
 * stepper cannot show once labels are truncated on a phone.
 *
 * The rail is an ordered list with `aria-current="step"`. Steps already
 * visited are buttons you can go back to; steps ahead are plain text, and
 * are not focusable — offering a tab stop that does nothing is worse than
 * not offering it.
 *
 * The option groups are real radios (`role` comes free from `type="radio"`),
 * wired into one `<fieldset>` with a `<legend>`. That is what makes arrow
 * keys move between options and what makes the group announce its question
 * before its answers. The card look is a styled `<label>` over a visually
 * hidden input — never a div with `onClick`, which loses all of it.
 */

import * as React from 'react'
import { Check, ChevronLeft, Rocket } from 'lucide-react'

export interface WizardOption {
  value: string
  label: string
  description: string
}

export interface WizardStep {
  id: string
  title: string
  question: string
  options: WizardOption[]
}

export interface SetupWizardProps {
  brand?: string
  steps?: WizardStep[]
  finishLabel?: string
  completeTitle?: string
  completeBody?: string
  onFinish?: (answers: Record<string, string>) => void
  className?: string
}

const DEFAULT_STEPS: WizardStep[] = [
  {
    id: 'framework',
    title: 'Framework',
    question: 'What are you building with?',
    options: [
      { value: 'next', label: 'Next.js', description: 'App Router, server components' },
      { value: 'vite', label: 'Vite + React', description: 'Client-rendered SPA' },
      { value: 'remix', label: 'Remix', description: 'Nested routes and loaders' },
    ],
  },
  {
    id: 'styling',
    title: 'Styling',
    question: 'How do you write styles?',
    options: [
      { value: 'tailwind', label: 'Tailwind CSS', description: 'Utility classes' },
      { value: 'css', label: 'Plain CSS', description: 'Modules or global stylesheets' },
    ],
  },
  {
    id: 'team',
    title: 'Team',
    question: 'Who else needs access?',
    options: [
      { value: 'solo', label: 'Just me', description: 'You can invite people later' },
      { value: 'team', label: 'My team', description: 'We will ask for emails next' },
      { value: 'client', label: 'A client', description: 'Sets up a shared workspace' },
    ],
  },
]

export function SetupWizard({
  brand = 'Acme',
  steps = DEFAULT_STEPS,
  finishLabel = 'Finish setup',
  completeTitle = 'You are ready to go.',
  completeBody = 'We have configured your workspace from your answers. You can change any of it in Settings.',
  onFinish,
  className = '',
}: SetupWizardProps) {
  const [step, setStep] = React.useState(0)
  const [answers, setAnswers] = React.useState<Record<string, string>>({})
  const [done, setDone] = React.useState(false)

  const current = steps[step]
  const answered = current ? answers[current.id] : undefined
  const isLast = step === steps.length - 1

  function choose(value: string) {
    if (!current) return
    setAnswers((a) => ({ ...a, [current.id]: value }))
  }

  function advance() {
    if (!answered) return
    if (isLast) {
      setDone(true)
      onFinish?.(answers)
    } else {
      setStep((s) => s + 1)
    }
  }

  return (
    <section className={`mx-auto w-full max-w-5xl px-4 py-12 sm:px-6 ${className}`}>
      <div className="grid gap-8 rounded-2xl border border-border/60 bg-card/40 p-6 sm:p-8 md:grid-cols-[220px_1fr] md:gap-12">
        {/* -- Rail ---------------------------------------------------- */}
        <div>
          <div className="flex items-center gap-2.5">
            <span
              aria-hidden
              className="flex h-8 w-8 items-center justify-center rounded-lg bg-gradient-to-br from-primary to-emerald-600 text-xs font-black text-primary-foreground"
            >
              {brand.slice(0, 1)}
            </span>
            <span className="font-bold tracking-tight">{brand}</span>
          </div>

          <ol className="mt-6 space-y-1">
            {steps.map((s, i) => {
              const state = done || i < step ? 'complete' : i === step ? 'current' : 'upcoming'
              const row = (
                <>
                  <span
                    className={`flex h-6 w-6 shrink-0 items-center justify-center rounded-full border text-[11px] font-bold ${
                      state === 'complete'
                        ? 'border-primary bg-primary text-primary-foreground'
                        : state === 'current'
                          ? 'border-primary text-primary'
                          : 'border-border/60 text-muted-foreground'
                    }`}
                  >
                    {state === 'complete' ? <Check aria-hidden className="h-3 w-3" /> : i + 1}
                  </span>
                  <span className="text-sm font-medium">{s.title}</span>
                  {state === 'complete' ? <span className="sr-only">completed</span> : null}
                </>
              )

              return (
                <li key={s.id}>
                  {/* Visited steps are navigable; steps ahead are not
                      focusable, because a tab stop that does nothing is
                      worse than no tab stop. */}
                  {state === 'complete' && !done ? (
                    <button
                      type="button"
                      onClick={() => setStep(i)}
                      className="flex w-full items-center gap-2.5 rounded-lg px-2 py-2 text-start transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
                    >
                      {row}
                    </button>
                  ) : (
                    <div
                      aria-current={state === 'current' ? 'step' : undefined}
                      className={`flex items-center gap-2.5 px-2 py-2 ${
                        state === 'upcoming' ? 'text-muted-foreground' : ''
                      }`}
                    >
                      {row}
                    </div>
                  )}
                </li>
              )
            })}
          </ol>
        </div>

        {/* -- Panel --------------------------------------------------- */}
        <div className="min-h-80">
          {done || !current ? (
            <div className="flex h-full flex-col items-center justify-center text-center">
              <span className="flex h-12 w-12 items-center justify-center rounded-full bg-primary/15 text-primary">
                <Rocket aria-hidden className="h-6 w-6" />
              </span>
              <h2 className="mt-4 text-xl font-bold tracking-tight">{completeTitle}</h2>
              <p className="mt-2 max-w-sm text-sm text-muted-foreground">{completeBody}</p>
            </div>
          ) : (
            <>
              <fieldset>
                <legend className="text-xl font-bold tracking-tight">{current.question}</legend>

                <div className="mt-6 space-y-3">
                  {current.options.map((option) => {
                    const id = `${current.id}-${option.value}`
                    const selected = answered === option.value
                    return (
                      <label
                        key={option.value}
                        htmlFor={id}
                        className={`flex cursor-pointer items-start gap-3 rounded-xl border p-4 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-ring ${
                          selected
                            ? 'border-primary bg-primary/5'
                            : 'border-border/60 hover:border-border hover:bg-muted/40'
                        }`}
                      >
                        <input
                          id={id}
                          type="radio"
                          name={current.id}
                          value={option.value}
                          checked={selected}
                          onChange={() => choose(option.value)}
                          className="sr-only"
                        />
                        <span
                          aria-hidden
                          className={`mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border ${
                            selected ? 'border-primary bg-primary' : 'border-border'
                          }`}
                        >
                          {selected ? (
                            <span className="h-2 w-2 rounded-full bg-primary-foreground border border-transparent" />
                          ) : null}
                        </span>
                        <span className="min-w-0">
                          <span className="block text-sm font-semibold">{option.label}</span>
                          <span className="mt-0.5 block text-xs text-muted-foreground">
                            {option.description}
                          </span>
                        </span>
                      </label>
                    )
                  })}
                </div>
              </fieldset>

              <div className="mt-8 flex items-center justify-between gap-3">
                <button
                  type="button"
                  onClick={() => setStep((s) => Math.max(0, s - 1))}
                  disabled={step === 0}
                  className="inline-flex h-11 items-center gap-1 rounded-xl border border-border/60 px-4 text-sm font-semibold transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
                >
                  <ChevronLeft aria-hidden className="h-4 w-4 rtl:rotate-180" />
                  Back
                </button>
                <button
                  type="button"
                  onClick={advance}
                  disabled={!answered}
                  className="inline-flex h-11 items-center rounded-xl bg-primary px-6 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-40"
                >
                  {isLast ? finishLabel : 'Continue'}
                </button>
              </div>
            </>
          )}
        </div>
      </div>
    </section>
  )
}

Before you paste

  • Styling is Tailwind utility classes on semantic tokens (bg-card, text-muted-foreground) — it inherits your theme instead of overriding it.
  • Install: npm i lucide-react
  • Every prop has a default, so it renders standalone before you wire it up.

Where it goes

Drop it at components/setup-wizard.tsx and import it where you need the section:

import { SetupWizard } from '@/components/setup-wizard'

Customize

3 of this block’s props are simple enough to drive from here. Change them and the block below re-renders — it is the same component whose source is above, not a mock of it. Everything else it accepts is in the table underneath.

Props

Read out of the component’s own type and signature, so this cannot drift from the source below. Every prop has a default — the component renders standalone before you pass it anything.

PropTypeDefault
brandstring'Acme'
stepsWizardStep[]DEFAULT_STEPS
finishLabelstring'Finish setup'
completeTitlestring'You are ready to go.'
completeBodystring—
onFinish(answers: Record<string, string>) => void—
classNamestring''

Not using React?

The same block rendered once to markup, wrapped as a file your framework compiles. Tailwind classes are framework-agnostic, so the design transfers intact — the behaviour does not.

This block is interactive. The markup below is its initial state with the event handlers stripped — you will need to re-wire the behaviour in your framework.

setup-wizard.html
<!--
  Guided Setup Wizard — markup from the Hoverlab catalog.

  This is the block rendered once to HTML and wrapped as a component
  file. It is not a port of the React source: the Tailwind classes carry
  the design, which is the part that took the work, and they are the same
  in every framework.

  This block is interactive in React and the handlers are NOT here.
  Buttons, toggles and menus render in their initial state and do
  nothing until you wire them up.
-->
<section class="mx-auto w-full max-w-5xl px-4 py-12 sm:px-6 ">
  <div class="grid gap-8 rounded-2xl border border-border/60 bg-card/40 p-6 sm:p-8 md:grid-cols-[220px_1fr] md:gap-12">
    <div>
      <div class="flex items-center gap-2.5">
        <span aria-hidden="true" class="flex h-8 w-8 items-center justify-center rounded-lg bg-gradient-to-br from-primary to-emerald-600 text-xs font-black text-primary-foreground">A</span>
        <span class="font-bold tracking-tight">Acme</span>
      </div>
      <ol class="mt-6 space-y-1">
        <li>
          <div aria-current="step" class="flex items-center gap-2.5 px-2 py-2 ">
            <span class="flex h-6 w-6 shrink-0 items-center justify-center rounded-full border text-[11px] font-bold border-primary text-primary">1</span>
            <span class="text-sm font-medium">Framework</span>
          </div>
        </li>
        <li>
          <div class="flex items-center gap-2.5 px-2 py-2 text-muted-foreground">
            <span class="flex h-6 w-6 shrink-0 items-center justify-center rounded-full border text-[11px] font-bold border-border/60 text-muted-foreground">2</span>
            <span class="text-sm font-medium">Styling</span>
          </div>
        </li>
        <li>
          <div class="flex items-center gap-2.5 px-2 py-2 text-muted-foreground">
            <span class="flex h-6 w-6 shrink-0 items-center justify-center rounded-full border text-[11px] font-bold border-border/60 text-muted-foreground">3</span>
            <span class="text-sm font-medium">Team</span>
          </div>
        </li>
      </ol>
    </div>
    <div class="min-h-80">
      <fieldset>
        <legend class="text-xl font-bold tracking-tight">What are you building with?</legend>
        <div class="mt-6 space-y-3">
          <label for="framework-next" class="flex cursor-pointer items-start gap-3 rounded-xl border p-4 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-ring border-border/60 hover:border-border hover:bg-muted/40">
            <input id="framework-next" type="radio" class="sr-only" name="framework" value="next" />
            <span aria-hidden="true" class="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border border-border"></span>
            <span class="min-w-0">
              <span class="block text-sm font-semibold">Next.js</span>
              <span class="mt-0.5 block text-xs text-muted-foreground">App Router, server components</span>
            </span>
          </label>
          <label for="framework-vite" class="flex cursor-pointer items-start gap-3 rounded-xl border p-4 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-ring border-border/60 hover:border-border hover:bg-muted/40">
            <input id="framework-vite" type="radio" class="sr-only" name="framework" value="vite" />
            <span aria-hidden="true" class="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border border-border"></span>
            <span class="min-w-0">
              <span class="block text-sm font-semibold">Vite + React</span>
              <span class="mt-0.5 block text-xs text-muted-foreground">Client-rendered SPA</span>
            </span>
          </label>
          <label for="framework-remix" class="flex cursor-pointer items-start gap-3 rounded-xl border p-4 transition-colors has-focus-visible:ring-2 has-focus-visible:ring-ring border-border/60 hover:border-border hover:bg-muted/40">
            <input id="framework-remix" type="radio" class="sr-only" name="framework" value="remix" />
            <span aria-hidden="true" class="mt-0.5 flex h-5 w-5 shrink-0 items-center justify-center rounded-full border border-border"></span>
            <span class="min-w-0">
              <span class="block text-sm font-semibold">Remix</span>
              <span class="mt-0.5 block text-xs text-muted-foreground">Nested routes and loaders</span>
            </span>
          </label>
        </div>
      </fieldset>
      <div class="mt-8 flex items-center justify-between gap-3">
        <button type="button" disabled="" class="inline-flex h-11 items-center gap-1 rounded-xl border border-border/60 px-4 text-sm font-semibold transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-left h-4 w-4 rtl:rotate-180" aria-hidden="true"><path d="m15 18-6-6 6-6"></path></svg>Back</button>
        <button type="button" disabled="" class="inline-flex h-11 items-center rounded-xl bg-primary px-6 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-40">Continue</button>
      </div>
    </div>
  </div>
</section>
  • This is rendered HTML, not a translation of the React source. The Tailwind classes carry the design and work in any framework.
  • It is one frame: the component in its initial state, with no props applied beyond the defaults.
  • This block is interactive in React — toggles, menus or form state. None of that survives here; the markup is the closed/default state and the handlers are gone. Re-wire them in your own framework.
  • Requires Tailwind, and the design tokens the classes reference (bg-card, text-muted-foreground, and so on). The template ZIPs ship a globals.css that defines them.

What each framework gets across the whole catalog — effects convert properly; this rung is markup.

For AI

The component, its props, the design tokens it expects and the command that installs it — as one prompt. Paste it into Claude, Cursor, v0 or ChatGPT and what they build around it will match the rest of the catalog instead of inventing its own system.

See the prompt

Used in these pages

Want the whole screen instead of this one section? Open a page and copy it entire.

7 more blocks in Onboarding

All of them free to read, copy and install — no account, no locked tiles, no watermarked preview. The whole catalog is open, and so are the API and the CLI.

Browse Onboarding

Shipping one commercially

Copying the code is free. Putting it in client work or a paid product is what Pro is for — the licence, not the access.

  • A commercial licence for everything in the catalog
  • Unlimited bundle exports, in Vue, Svelte and Tailwind
  • One payment — no subscription, nothing to renew
Pro — $79 once

More Onboarding blocks

View category
Open the full page for this block

Setup Checklist with Progress

The get-started card that ships with its first item already ticked, a native <progress> element rather than a div bar, and a dismiss control that appears only once there is nothing left to abandon.

Onboarding230 lines1 dep
Open the full page for this block

Team Invite Step

The onboarding step where a product becomes multiplayer: pasted addresses split into chips, typos marked rather than dropped, and an honest way to skip.

Onboarding279 lines1 dep
Open the full page for this block

Product Tour Coach Mark

A tour step anchored to the control it explains, with a spotlight cut by one spread shadow, a visible step count and focus that follows the step.

Onboarding262 lines1 dep
Open the full page for this block

Role Picker

The "what best describes you" step, asked honestly — every option states what it actually changes, the skip is visible and names what you get instead, and the choice is reversible.

Onboarding191 lines1 dep
Open the full page for this block

Import or Start Empty

The empty product’s real first question. Sample data is offered with equal weight rather than as grey small print, every connector names its scope before the redirect, and each option carries the honest duration.

Onboarding216 lines1 dep
Open the full page for this block

Workspace Setup Form

The first screen after signup, asking only the two things that cannot be changed silently later.

Onboarding176 linesNo deps
Open the full page for this block

Data Migration Split

What a migration actually moves and what it cannot, stated before the switch rather than discovered after it.

Onboarding158 linesNo deps