Multi-step Form

Installation

$ npx shadcn@latest add https://goodui.dev/r/multi-step-form.json

The file lands in components/goodui/multi-step-form.tsx and is yours to edit. With the @goodui registry added, npx shadcn@latest add @goodui/multi-step-form works too.

Usage

import { MultiStepForm, type FormStep } from "@/components/goodui/multi-step-form"
import { Input } from "@/components/goodui/input"

type Signup = { name: string; email: string; company: string }

const isEmailFree = async (email: string) => (await fetch("/api/email-free?email=" + encodeURIComponent(email))).ok

const steps: FormStep<Signup>[] = [
  {
    id: "you",
    title: "About you",
    fields: ["name", "email"],
    validate: async (v) => ({
      name: v.name.trim() ? undefined : "Enter your name.",
      email: (await isEmailFree(v.email)) ? undefined : "That email already has an account.",
    }),
    content: ({ values, setValue, error }) => (
      <>
        <Input label="Name" name="name" value={values.name} onValueChange={(s) => setValue("name", s)}
          state={error("name") ? "error" : "default"} message={error("name")} />
        <Input label="Email" name="email" type="email" value={values.email} onValueChange={(s) => setValue("email", s)}
          state={error("email") ? "error" : "default"} message={error("email")} />
      </>
    ),
  },
  {
    id: "company",
    title: "Company",
    optional: true,
    fields: ["company"],
    content: ({ values, setValue }) => <Input label="Company" value={values.company} onValueChange={(s) => setValue("company", s)} />,
  },
]

export function SignupWizard() {
  return (
    <MultiStepForm<Signup>
      steps={steps}
      review
      defaultValues={{ name: "", email: "", company: "" }}
      onSubmit={async (values) => {
        await fetch("/api/signup", { method: "POST", body: JSON.stringify(values) })
      }}
    />
  )
}

When to use

Examples

const [draft, setDraft] = React.useState<MultiStepFormSnapshot<Signup> | null>(null)
React.useEffect(() => {
  const raw = localStorage.getItem("signup-draft")
  if (raw) setDraft(JSON.parse(raw))
}, [])

<MultiStepForm<Signup>
  key={draft ? "draft" : "new"}
  steps={steps}
  defaultValues={draft?.values ?? empty}
  defaultStep={draft?.step}
  defaultCompleted={draft?.completed}
  onPersist={(snap) => localStorage.setItem("signup-draft", JSON.stringify(snap))}
/>

// Select, ToggleGroup and other composite controls: wrap them with data-field so the first
// invalid one gets focus.
<div data-field="plan">
  <ToggleGroup aria-label="Plan" value={values.plan} onValueChange={(p) => setValue("plan", p)} items={plans} />
  {error("plan") && <p className="text-xs text-red-600">{error("plan")}</p>}
</div>

<MultiStepForm steps={steps} onSubmit={save}
  success={({ values, reset }) => (
    <div className="text-center">
      <p className="font-semibold">Welcome, {values.name}!</p>
      <button onClick={reset}>Add another</button>
    </div>
  )} />

API reference

Accessibility

• •Renders a native <form noValidate>; the primary button is type="submit", Back and Skip are type="button".
• •The header is a <nav> with an ordered list; the current step has aria-current="step" and each step has a hidden status ("completed", "skipped", "needs attention").
• •On every step change a polite live region announces "Step 2 of 4: Contact" and focus moves to the new step's heading, so keyboard and screen-reader users start at the top of the step.
• •When validation fails, the live region announces how many fields need attention and focus moves to the first invalid field (found by data-field, then name, then id). Step-level errors and submit errors render with role="alert".
• •While an async validator or onSubmit runs, the primary button shows a spinner with aria-busy and the live region says "Checking…" or "Submitting…".
• •Every built-in string (buttons, announcements, status words, review texts) goes through labels.

Motion

• •slide: the outgoing step leaves 28px against the direction in 140 ms and the new one enters with a spring (stiffness 420, damping 38); directions flip under dir="rtl".
• •fade: opacity with a 6px rise. none: instant.
• •Header lines fill over 400 ms as steps complete; the progress bar eases over 450 ms. The default success check pops in with a spring and draws its stroke over 500 ms.
• •Reduced motion: step changes are instant and all CSS transitions and animations inside the form are off.

• •Only the current step is mounted. Validators run on Continue, on header jumps and once more for every non-skipped step on submit, never on keystrokes.
• •onPersist runs after every value change; debounce it yourself if it writes to a server.

Notes for AI

Coding agents read these rules through MCP and llms.txt, or paste this page with Copy page.

FAQ

Related