Multi-Step Form

InstallCopy Anchor Link

pnpm exec vegastack-design verify multi-step-form

pnpm dlx shadcn@4.21.0 add @vegastack/multi-step-form

UsageCopy Anchor Link

Opt-in URL synchronization pushes intentional step changes and replaces only corrections. Persisted flows retain sealed steps by stable IDs, including across remounts.

A MultiStepFormStep mounts the first time its step is current and then stays mounted, hidden, while another step is current: going back keeps typed answers and loaded data, and a move never re-runs the body's effects. Steps never visited are not mounted. The entrance animation plays only when the flow moves, never on the first paint.

import {
  MultiStepForm,
  MultiStepFormNav,
  MultiStepFormStep,
  MultiStepFormActions,
} from "@/components/ui/multi-step-form";

<MultiStepForm
  steps={[
    { id: "account", label: "Account" },
    { id: "billing", label: "Billing" },
    { id: "review", label: "Review" },
  ]}
>
  <MultiStepFormNav aria-label="Signup" />
  <MultiStepFormStep id="account">…</MultiStepFormStep>
  <MultiStepFormStep id="billing">…</MultiStepFormStep>
  <MultiStepFormStep id="review">…</MultiStepFormStep>
  <MultiStepFormActions />
</MultiStepForm>;

The steps array declares the flow — labels, branches, guards. Each MultiStepFormStep declares one step's body, and only the current one renders. The body is whatever you put in it: a Field form, a review table, an upload surface, a chart, nothing.

MultiStepFormActions is as plain as an overlay footer: no divider, no background. The row has one order everywhere — [‹] [Cancel] …… [status] [Save] [›]: a ‹ icon button (Back, secondary, not shown on the first step) then Cancel (ghost) at the start; the status ("Saving…"/"Saved"), an optional outline save and a › icon button (Next, primary) at the end. On the last step the finish action takes the primary slot with its text label ("Create", "Save product", "Done"). See Footer.

ScopeCopy Anchor Link

It owns the flow and refuses to own your form, which is what keeps it at zero new dependencies.

Adding React Hook Form or Zod here would each be a new sanctioned dependency exception. Because a guard is just a function returning a promise, neither is needed.

AnatomyCopy Anchor Link

ExamplesCopy Anchor Link

BranchingCopy Anchor Link

A step whose when is false leaves the rail, the count and the sequence — so "step 3 of 4" stays true when a branch drops one. Switch the account type below and watch a step appear and disappear.

Guards that run, and failCopy Anchor Link

beforeNext returns true to pass or a sentence to refuse, and may be async — the step goes loading, the action shows a spinner, and the flow never advances optimistically. A refusal that came from a check that ran and failed is an assertive Alert directly above the action row, tied to the button through aria-describedby. This step also carries lock, so passing it seals everything behind it.

A gate that isn't an errorCopy Anchor Link

A step that simply is not finished yet is tone: "soft" — a quiet polite line, and the rail is left alone, because "not yet" is not "broken". Press Continue with the field empty.

FooterCopy Anchor Link

The footer is the same everywhere. ‹ and › are icon buttons named "Back" and "Next" (their accessible name and tooltip come from backLabel and nextLabel), with the same 1px press nudge as every button. Back is not rendered on the first step. start takes Cancel (MultiStepFormExit), status takes the save state, and secondary takes the optional outline save, MultiStepFormSave — "Save draft" in a create flow, "Save" in an edit flow that saves explicitly, "Done" in a flow that saves as you go. On the last step the finish action takes the primary slot with submitLabel, and a MultiStepFormSave whose text equals that label steps aside (hideOnLast overrides it) — a footer never shows two saves.

<MultiStepForm steps={steps} submitLabel="Save product">
  …
  <MultiStepFormActions
    start={<MultiStepFormExit />}
    status={<AutoSaveIndicator status={status} />}
    secondary={
      <MultiStepFormSave onClick={saveDraft}>Save draft</MultiStepFormSave>
    }
  />
</MultiStepForm>

Editing an existing recordCopy Anchor Link

Mark a step satisfied when its data is already there. That one predicate decides four things at once: the rail starts complete, jumping is offered, a deep link opens exactly where it points instead of rewinding, and a phone gets the tappable section list instead of a progress line. There is no mode="create" | "edit" to keep in sync.

Optional stepsCopy Anchor Link

An optional step carries the affix and offers Skip, which advances without running beforeNext and records the step as skipped rather than complete.

Sticky actionsCopy Anchor Link

On a long step, pass sticky to MultiStepFormActions so the refusal and the action row stay at the bottom of the scroll area while the step scrolls under them — sticky="narrow" pins only while the form is narrower than its @md container rung, a phone. The pinned row keeps the same gap above its buttons as below them, in the surface it sits on, so content passing under it stops short of the buttons. The row reports data-stuck while it is actually pinned over content and then shows a hairline on its top edge, which takes no space; resting at the end of the step it shows none and sits where an unpinned row would. The focus order does not change.

Inside a dialogCopy Anchor Link

layout="panel" is the shape a wizard takes in a Dialog, Sheet or Drawer: the nav and the action row hold their place while the step body becomes the one scrolling region, so the frame cannot grow past the viewport and carry its own footer off screen. This example also carries dirty — type into the first field, then press Cancel.

Steps across the top, checks that clear themselvesCopy Anchor Link

<MultiStepFormNav orientation="horizontal" /> puts the rail above the steps — the layout for a full-page form, with no side column. A step's validate is a pure, synchronous check run before beforeNext; its refusal re-reads the check on every render and clears itself (with the rail's error mark) as soon as the answers pass. start puts Cancel (MultiStepFormExit, a ghost button) right after Back at the start of the action row.

Saving as you goCopy Anchor Link

For a record that already exists, save each change instead of asking for Save: useAutoSave from auto-save-input sends the changed fields after a pause, and the action row's status and secondary slots carry an AutoSaveIndicator and <MultiStepFormSave>Done</MultiStepFormSave>, in that order before ›: [‹] …… ✓ Saved [Done] [›]. With submitLabel="Done" the last step shows one primary Done. mobileNav="stepper" keeps the rail on a phone, where it collapses to the step's label, "Step n of N" and a progress bar, instead of the section list.

Leaving with unsaved workCopy Anchor Link

MultiStepFormExit leaves the flow, asking first when dirty says the current step holds work that would be lost. With nothing dirty it simply calls onExit — a confirmation nobody needs is the fastest way to teach people to dismiss confirmations unread. While dirty is true the browser also warns on a refresh or a closed tab, which is the half no component can fake.

<MultiStepForm steps={steps} dirty={form.isDirty} onExit={() => setOpen(false)}>
  …
  <MultiStepFormActions start={<MultiStepFormExit />} />
</MultiStepForm>

Steps in the routeCopy Anchor Link

A host that keeps the step in its route (/products/new/pricing) owns it: pass step from the route and navigate in onStepChange. The second argument says how: replace is false for Next, Back and a jump from the rail — push a history entry — and true when the form corrected the step itself, such as a pasted link to a step whose prerequisites are not met yet, which it clamps to the furthest reachable step. Replacing keeps Back from returning to a step the form refused.

const router = useRouter();

<MultiStepForm
  steps={steps}
  step={params.step}
  onStepChange={(id, { replace }) =>
    replace
      ? router.replace(`/products/new/${id}`)
      : router.push(`/products/new/${id}`)
  }
>
  …
</MultiStepForm>;

Use the controlled step alone for a route-driven form; urlSync (the #step= hash) and persistKey are for hosts that do not own the address.

API ReferenceCopy Anchor Link

StepCopy Anchor Link

RefusalCopy Anchor Link

NavCopy Anchor Link

ActionsCopy Anchor Link

SaveCopy Anchor Link

AccessibilityCopy Anchor Link

• Exactly one focus move per transition. Stepper moves focus to the new step's label; this component deliberately does not also focus the first field, and mounts no live region for step changes — the focused label and aria-current="step" are the announcement.
• A refusal that follows a failed check is role="alert", which is assertive — correct here and only here, because it appears after mount in response to something the user did. A soft gate is a polite role="status".
• The refusal is referenced by the forward action's aria-describedby, so the reason reads out with the control it blocks (WCAG 3.3.1), and it persists rather than disappearing like a toast.
• Sealed and unreachable steps are not focus targets; the phone section rows are Buttons, so they clear the 24px touch floor.
• ‹ and › are icon-only, so each carries its label as aria-label ("Back", "Next") and shows it in a tooltip on hover and focus; on the last step the finish action is a text button.
• A hash naming a step the guards forbid is ignored and the bar corrected, so a pasted link cannot bypass a gate or leave the URL disagreeing with the screen.

Do / Don'tCopy Anchor Link