fma-ds

Form Wizard

A form in steps, in a dialog or on a page (a new customer, an onboarding).

originalMITexperimentalChangelogRegistry JSON

Overview

FormWizard takes steps ({ title, description } per step) and the current step, controlled (step/onStepChange) or not (defaultStep).

  • Navigation: it's a react-aria Form whose submit is Next, so Enter advances and the current step's fields validate natively (only that step is mounted). Then onNext(step) runs — validate or save there (react-hook-form's trigger). Returning false or throwing keeps the user on the step, and a promise shows Next as pending. Finish runs onNext of the last step and then onComplete.
  • `FormWizardSteps`: the stepper list. Earlier steps are reachable, later ones only through Next. Titles show when the wizard is wide enough for that many steps; narrower, only the numbers, with the current title under them (container query).
  • `FormWizardStep`: holds a step's fields; after Back or Next, focus moves to its first field.
  • `FormWizardFooter`: the progress ("Step 2 of 4", announced politely), children before Back (a dialog's Cancel), Back and Next/Finish.

The values stay in the app; with react-hook-form, keep shouldUnregister off.

Built-in text is in English; translate it with i18n.labels.

Installation

  1. 1

    Register the @fma-ds namespace in components.json (once)

    components.json
    {  "registries": {    "@fma-ds": "https://ds.fmartinsandre.dev.br/r/{name}.json"  }}
  2. 2

    Add the item

    pnpm dlx shadcn@latest add @fma-ds/form-wizard

    Files land in components/fma-ds/form-wizard/form-wizard.tsx; npm and registry dependencies are installed along with them.

Dependencies

npm
cn@^0.5.0lucide-react@^1.61.0react-aria-components@^1.22.1