@bonhomie/react-flow-form

🎯 Why use React Flow Form?

Building multi-step forms is one of the most repeated tasks in modern apps:

• KYC onboarding
• User registration & verification
• Checkout flows
• Pricing/plan selection
• Multi-screen surveys
• Job application flows
• SaaS onboarding steps

Developers hate rewriting: ✔ navigation logic ✔ validation ✔ transitions ✔ persistence ✔ step management

This library makes it plug-and-play.

🚀 Features

🌊 Core Multi-Step Engine

• Next & Previous step navigation
• Step metadata (title, description, rules…)
• Step-level validation
• Detect if user is on last step
• Progress tracking

💾 Persistence

• Auto-save form state to localStorage
• Auto-restore on page reload
• One-line enable/disable with storageKey

🔄 Transition Support

• Built-in fade transition
• Custom transitions allowed

🧩 Components Included

• <FlowForm> wrapper
• <Step> component
• <ProgressBar> indicator

🧠 Super Simple Hook API

• useMultiStepForm()
• Clean access to data, update, next, back, errors, step

📦 Installation

npm install @bonhomie/react-flow-form

🧪 Quick Start Example

import {
  FlowForm,
  Step,
  ProgressBar,
  useMultiStepForm
} from "@bonhomie/react-flow-form";

export default function SignupFlow() {
  const {
    data,
    update,
    next,
    back,
    errors,
    currentStep,
    totalSteps,
    step
  } = useMultiStepForm({
    storageKey: "signup-flow",
    initialData: { email: "", name: "" },
    steps: [
      {
        id: "email",
        validate: (data) =>
          data.email.includes("@") ? true : { email: "Invalid email" },
      },
      {
        id: "profile",
        validate: () =>
          true // No errors
      }
    ],
    onComplete: (data) => {
      console.log("FINISHED:", data);
    }
  });

  return (
    <FlowForm
      step={step}
      currentStep={currentStep}
      totalSteps={totalSteps}
    >
      {(step, idx) => (
        <>
          <ProgressBar current={currentStep} total={totalSteps} />

          {step.id === "email" && (
            <Step>
              <h2>Enter Email</h2>
              <input
                value={data.email}
                onChange={(e) => update("email", e.target.value)}
              />
              {errors.email && <p>{errors.email}</p>}
              <button onClick={next}>Next</button>
            </Step>
          )}

          {step.id === "profile" && (
            <Step>
              <h2>Your Name</h2>
              <input
                value={data.name}
                onChange={(e) => update("name", e.target.value)}
              />
              <div style={{ marginTop: 16 }}>
                <button onClick={back}>Back</button>
                <button onClick={next}>Finish</button>
              </div>
            </Step>
          )}
        </>
      )}
    </FlowForm>
  );
}

⚙️ API Reference

useMultiStepForm(options)

Options

| Option | Type | Description | | ------------- | -------------- | ------------------------------------------------ | | steps | array | Required. Each step contains { id, validate }. | | initialData | object | Default form state. | | storageKey | string or null | Enable persistence + restore. | | onComplete | function | Fired when last step finishes. |

Returned values

| Value | Description | | --------------------- | --------------------------------- | | data | All form state. | | update(name, value) | Update fields. | | next() | Validate + move forward. | | back() | Move backward. | | errors | Validation errors per step. | | currentStep | Number index. | | totalSteps | Total number of steps. | | step | Current step object. | | isLast | Is the current step the last one? |

🧱 Components

<FlowForm>

Props:

| Prop | Description | | ------------- | ---------------------------- | | step | Step object returned by hook | | currentStep | Current step index | | totalSteps | Number of steps | | transition | "fade" (default) |

<Step>

Light wrapper for step content.

<Step>
  <h1>Page 1</h1>
</Step>

<ProgressBar>

<ProgressBar current={0} total={4} />

🗂 Recommended Patterns

1. KYC flow

• Email
• Personal details
• Address
• Document upload
• Review & Submit

2. Checkout flow

• Contact info
• Shipping
• Payment
• Confirm

3. Pricing wizard

• Business size
• Use cases
• Budget
• Plan selection

4. Onboarding flow

• Preferences
• Goals
• Customization

🔥 Enterprise Features

This library supports:

✔ Full-screen step flows ✔ External form libraries (Formik, React Hook Form) ✔ Server-side validation ✔ Custom transitions ✔ Auto-restoration even after browser crash ✔ Offline-safe state

⚠️ SSR Notes

• localStorage usage is guarded
• For SSR (Next.js), wrap inside useEffect when using persistence
• Works perfectly in client-side rendered React apps

🩹 Troubleshooting

“Validation not running”

Make sure your step contains:

validate: (data) => true or { field: "error" }

“Form not saving to storage”

Set:

storageKey: "my-form"

“Going next does nothing”

Your validator returned an object (errors).

🗺 Roadmap

• Animations presets (slide, zoom, curtain)
• TypeScript rewrite
• Schema-based validation integration (Zod/Yup optional addon)
• Form field builder templates
• Visual form designer (Pro version)

📄 License

MIT — Free for commercial and personal use.

👨‍💻 Author

Bonhomie Full-stack Web & Mobile Developer Creator of @bonhomie toolkits and developer utilities.