Form Wizard React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Form Wizard is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import FormWizard from @/components/ui/form-wizard.

import { Controller, FormProvider, useForm, useFormContext } from "react-hook-form"
import { FormWizard, FormWizardSummary, useFormWizardValidation, type WizardStep } from "@/components/ui/form-wizard"
import { Input } from "@/components/ui/input"
import { CurrencyInput } from "@/components/ui/currency-input"

type Listing = { title: string; price: number | null }

function Details() {
  const { register, control, trigger, formState } = useFormContext<Listing>()
  useFormWizardValidation(() => trigger(["title", "price"]))
  return (
    <div className="flex flex-col gap-4">
      <Input
        label="Title"
        error={formState.errors.title?.message}
        {...register("title", { minLength: { value: 10, message: "The title needs at least 10 characters" } })}
      />
      <Controller
        name="price"
        control={control}
        rules={{ required: "Add a price" }}
        render={({ field, fieldState }) => (
          <CurrencyInput label="Price" currency="USD" locale="en-US" value={field.value} onValueChange={field.onChange} onBlur={field.onBlur} ref={field.ref} error={fieldState.error?.message} />
        )}
      />
    </div>
  )
}

function Review() {
  const { getValues } = useFormContext<Listing>()
  return <FormWizardSummary editLabel="Edit" sections={[{ step: "details", items: [{ label: "Title", value: getValues("title") }] }]} />
}

const steps: WizardStep[] = [
  { id: "details", title: "Details", content: <Details /> },
  { id: "review", title: "Review", content: <Review /> },
]

export function PostListing() {
  const form = useForm<Listing>({ defaultValues: { title: "", price: null } })
  return (
    <FormProvider {...form}>
      <FormWizard
        steps={steps}
        labels={{ submit: "Publish", step: (i, n) => `Step ${i} of ${n}` }}
        onComplete={() => fetch("/api/listings", { method: "POST", body: JSON.stringify(form.getValues()) })}
      />
    </FormProvider>
  )
}

Props

• steps
  WizardStep[]

  { id, title, description?, icon?, content, optional?, validate? }. validate returns a boolean or a promise; a throw or rejection counts as failed and is logged. Alternatively pass <FormWizardStep> children with the same props (content is their children). An empty list renders nothing.

• stepperdefault "horizontal"
  "horizontal" | "vertical" | "progress" | "dots" | "none"

  The header from 768px up: numbered markers with connectors, a side column with descriptions, a progress bar with the step title, dots for onboardings, or nothing. Below 768px every stepper except none becomes the compact progress header.

• lineardefault true
  boolean

  Only Continue moves forward; completed steps stay clickable. false makes every step clickable (going forward still validates the current step first).

• sizedefault "md"
  "sm" | "md"

  Markers 24 / 28px, step titles 13 / 14px, footer buttons sm / md.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The active marker, the connector and progress fills, completed markers' tint and the Continue button.

• colordefault ""
  string

  Any CSS color; replaces the tone everywhere. Text on the fill turns black or white by lightness.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape of the footer buttons, scaled per size like the button's.

• showStepHeadingdefault true
  boolean

  The step title and description above the fields. The title hides on its own wherever the header already shows it (phones, the progress stepper); false hides both but keeps the title for screen readers and as the focus target.

• fullScreenOnMobiledefault true
  boolean

  Below 768px the wizard fills its container's height: a sticky blurred header, a body that scrolls on its own and a sticky footer with 48px buttons (Continue full width, Back as an icon) padded for the safe area. Give the container a height (h-dvh for a page).

• animatedefault true
  boolean

  Steps slide 32px in the direction you move, the body's height follows on a spring, fills grow and a failed Continue shakes. false swaps steps instantly. Reduced motion always crossfades.

• keepMounteddefault false
  boolean

  Keeps every step mounted (inactive ones hidden and inert), for forms that keep their state in the DOM. react-hook-form does not need it: it keeps the values of unmounted fields.

• value
  string

  The current step id, controlled. Pair it with onValueChange. An unknown id shows the first step; a removed active step moves to the nearest one.

• defaultValuedefault ""
  string

  The starting step id; empty (or an unknown id) starts on the first step. In a linear wizard the steps before it count as completed.

• children
  ReactNode

  <FormWizardStep> elements instead of the steps array; other children are ignored.

• onValueChange
  (value: string) => void

  Called with the new step id on every step change.

• onComplete
  (event: FormEvent<HTMLFormElement>) => (void | Promise<unknown>)

  The last step's submit, after its validation. A promise shows the button loading, then a check (labels.done); a rejection shakes it. After an await read the form from event.target. Without onComplete a form action (formProps.action) runs instead.

• footer
  ReactNode

  Replaces the default footer; build one with useFormWizard() (a type="submit" button acts as Continue). null hides the footer.

• labels
  Partial<{ back; next; submit; skip; done; step: (index, count) => string; optional; completed; error; progress }>

  Every visible and announced string, merged over the English defaults: back "Back", next "Continue", submit "Submit", skip "Skip", done "Done", step (i, n) => "Step i of n", optional "Optional", completed "Completed", error "Needs attention" (both read after a step's title), progress "Progress" (names the stepper).

• formProps
  ComponentProps<"form">

  Extra props for the root <form> (action, id, method). Other unknown props land on the form too.

• classNames
  Partial<Record<"header" | "stepper" | "stepItem" | "stepMarker" | "stepTitle" | "stepDescription" | "connector" | "progress" | "progressBar" | "progressText" | "main" | "body" | "panel" | "panelTitle" | "panelDescription" | "footer" | "back" | "skip" | "next", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root <form>.

Parts

FAQ

Used in

More React form components