npm install react-multi-form-step react-hook-form @mantine/core @mantine/hooks @tabler/icons-react

✅ You also need to have Tailwind CSS and optionally shadcn/ui installed if you're using UI components like buttons or inputs.

🔧 Requirements
This package assumes your project is already using:

    React 18+

    Tailwind CSS

    React Hook Form

    Mantine UI (@mantine/core, @mantine/hooks)

    Optional: shadcn/ui or lucide-react for consistent styling and icons



✨ Features

    ✅ Seamless integration with react-hook-form

    ✅ Per-step field validation (only validate fields for the current step)

    ✅ Conditional logic for navigating between steps

    ✅ Fully customizable step components and layout

    ✅ Header and footer customization (add your own buttons)

    ✅ Modern UI powered by Mantine Stepper, Tailwind, and shadcn/ui

    ✅ TypeScript support with strong typing and field safety



🛠️ Usage
1. Create your form instance

import { useForm } from "react-hook-form";

const formMethods = useForm({
  mode: "onChange",
  defaultValues: {
    stepOne: {
      name: "",
      email: "",
    },
    stepTwo: {
      address: "",
    },
  },
});

2. Define your steps

Each step should include a label, the fields to validate in that step, and a component to render.

const steps = [
  {
    label: "Basic Info",
    fields: ["stepOne.name", "stepOne.email"],
    component: <BasicInfoStep formMethods={formMethods} />,
  },
  {
    label: "Address Info",
    fields: ["stepTwo.address"],
    component: <AddressStep formMethods={formMethods} />,
  },
];

3. Use the StepperForm component

import { StepperForm } from "react-multi-form-step";
import { FaCheck } from "react-icons/fa";
import { Send, Users } from "lucide-react";
import { IconCircleArrowRight } from "@tabler/icons-react";

<StepperForm
  steps={steps}
  onSubmit={(data) => console.log("Form submitted:", data)}
  formMethods={formMethods}
  icons={{
    completed: <FaCheck className="text-white" />,
  }}
  header={({ prevStep, isLastStep, nextStep, methods }) => (
    <div className="flex justify-between items-center mb-4">
      <button onClick={prevStep} className="btn-outline">Back</button>
      <button
        onClick={
          isLastStep
            ? methods.handleSubmit((data) => console.log("Submit", data))
            : nextStep
        }
        type={isLastStep ? "submit" : "button"}
        className="btn-primary flex items-center"
      >
        {isLastStep ? <Send size={18} className="me-2" /> : <IconCircleArrowRight className="me-2" />}
        {isLastStep ? "Submit" : "Next"}
      </button>
    </div>
  )}
/>



⚙️ Props Reference
Prop	Type	Required	Description
steps	StepConfig[]	✅	List of step configuration objects (label, fields, component)
onSubmit	(data: any) => void	✅	Callback triggered after final step submission
formMethods	UseFormReturn<T>	✅	Your useForm() instance
header	ReactNode or ({...}) => JSX	❌	Custom header with full control (e.g. for nav buttons like Back/Next)
footer	ReactNode or ({...}) => JSX	❌	Optional footer renderer
icons	{ completed?: ReactNode }	❌	Icon to show for completed steps



🧠 Field Validation
You only need to validate fields relevant to the current step — just include them in the fields array of the step object:

fields: ["user.name", "user.email"]

Only these fields will be validated before moving to the next step.
🧩 Example File Structure

src/
├─ components/
│  ├─ stepper/
│  │  └─ StepperForm.tsx
│  ├─ steps/
│  │  ├─ BasicInfoStep.tsx
│  │  └─ AddressStep.tsx
├─ App.tsx



📤 Contributing
Contributions are welcome! Follow these steps:

    Fork the repo

    Create a new branch: git checkout -b my-feature

    Make your changes

    Commit: git commit -m "Add feature"

    Push and open a Pull Request

Feel free to open issues for bugs, suggestions, or feature requests.
📎 Links

    🔗 NPM Package: https://www.npmjs.com/package/react-multi-form-step

    👨‍💻 Author: Mohamed Mubarak

    🌐 React Hook Form: https://react-hook-form.com

    📚 Mantine UI: https://mantine.dev