Multi-step formPro

• Type: Block

• Page: https://ui.xzero.co.uk/components/blocks/multi-step-form

• Markdown: https://ui.xzero.co.uk/components/blocks/multi-step-form/markdown

• Access: Xzero Pro

• Registry id: multi-step-form

• Source file: registry/components/multi-step-form/multi-step-form.tsx

• Built from: Input, Progress, Button

• Keywords: react multi step form, form wizard, step form, onboarding form, wizard component, multi page form

Use it when a form needs distinct steps. Keep the number of steps small and provide a clear completion action.

When to use

• Onboarding or intake flows split into a few short steps.
• Wizards that need Back and Continue, progress, and a success state out of the box.

When not to use

• Use stepper when you only need the progress indicator.
• Use checkout-flow for full page flows.
• Use onboarding-checklist for tasks done outside a form.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui-pro/multi-step-form

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { MultiStepForm } from "@/components/xzero/multi-step-form/multi-step-form";

export function Onboarding() {
  return (
    <MultiStepForm
      steps={[
        { id: "account", title: "Account", content: <AccountFields /> },
        { id: "team", title: "Team", description: "Who will you work with?", content: <TeamFields /> },
        { id: "plan", title: "Plan", content: <PlanFields /> },
      ]}
      onComplete={saveOnboarding}
    />
  );
}

API reference

MultiStepForm

A wizard that shows one fieldset per step with a progress list, Back and Continue actions, and a success state after the last step.

Prop	Type	Default	Description
steps (required)	FormStep[]	–	Steps in order. Renders nothing when empty.
onComplete	() => void	–	Called when the last step is submitted.
nextLabel	string	"Continue"	Submit label on every step except the last.
completeLabel	string	"Finish"	Submit label on the last step.
initialStep	number	0	Zero-based starting step, clamped to the range.

FormStep

Step type: { id: string; title: string; description?: string; content: ReactNode }. title becomes the fieldset legend and the progress label.

No props.

Keyboard interactions

Keys	Action
Enter	Submits the step (native form submit), advancing or finishing.
Tab	Moves through step fields and the Back and Continue buttons.

Accessibility

• Each step is a fieldset with a legend, and focus moves to the new legend (or the success heading) after navigation.
• Progress is a labelled nav with aria-current=step, plus a visually hidden aria-live line announcing Step 2 of 3.
• The success state is role=status. Native required and pattern constraints in step content block submit before the step advances.

Motion

• Steps slide 20px in the direction of travel while the shell springs to the new step's height.
• Completed markers draw a check, the step count rolls, and the submit button's width springs when the label changes.
• Reduced motion swaps steps, heights, and labels instantly.

Responsive behavior

• The progress list scrolls horizontally when steps overflow.
• Below 420px the progress header stacks with the step count on top and padding tightens.

Performance

• Only the active step is rendered, so keep field values in parent state.
• The shell springs to each step's height; step content is otherwise untouched.

Notes for AI

• Use for onboarding or intake flows split into a few short steps. Use stepper for a standalone progress indicator and checkout-flow for full page flows.
• Step content is rendered only while active, so keep field values in parent state; validation beyond native constraints is up to you.

Related

• Stepper: Show where a person is in a multi-step flow and what is done.
• Login and sign up: Sign up: An account creation flow with field validation, password strength, and a clear completion state.

Guidance for AI tools

Blocks are complete, self-contained screens with sample data. Replace the sample data and connect the callbacks described above. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt