React Multi-Step Form Builder

A highly customizable, type-safe React multi-step form library with progress tracking, validation, and beautiful UI components. Build complex onboarding flows, surveys, or registration processes with ease using JSON configuration.

Features

• 🎨 JSON-Powered - Define your entire form structure in a simple JSON configuration
• ✨ Smooth Transitions - Fluid, animated transitions between form steps
• 📊 Progress Tracking - Visual progress bar shows users their position in the flow
• ✅ Built-in Validation - Support for required fields and custom regex validation
• 🎯 Rich Form Elements - Text, email, password, select, textarea, radio, and checkbox groups
• 🔄 State Persistence - Save and restore form progress
• 💪 TypeScript - Fully typed for better developer experience
• 🎭 Customizable - Themeable components with Tailwind CSS
• ♿ Accessible - Built with accessibility in mind

Installation

# npm
npm install @yourscope/react-multi-step-form

# yarn
yarn add @yourscope/react-multi-step-form

# pnpm
pnpm add @yourscope/react-multi-step-form

Note: This library requires React 18+ and uses Tailwind CSS for styling.

Quick Start

1. Basic Usage

import React, { useState, useEffect } from 'react';
import { MultiStepForm, FormConfig, FormData } from '@yourscope/react-multi-step-form';

function App() {
  const [formConfig, setFormConfig] = useState<FormConfig | null>(null);

  useEffect(() => {
    // Load your form configuration
    fetch('/path/to/form-config.json')
      .then(res => res.json())
      .then(data => setFormConfig(data));
  }, []);

  const handleSubmit = (formData: FormData) => {
    console.log('Form submitted:', formData);
    // Send to your API, etc.
  };

  if (!formConfig) return <div>Loading...</div>;

  return (
    <div className="min-h-screen bg-gray-900 flex items-center justify-center p-4">
      <div className="w-full max-w-2xl">
        <MultiStepForm config={formConfig} onSubmit={handleSubmit} />
      </div>
    </div>
  );
}

2. Form Configuration Example

Create a JSON configuration file:

{
  "formId": "user-onboarding",
  "title": "Welcome Onboarding",
  "welcome": {
    "title": "Welcome!",
    "message": "Let's get you set up in just a few steps.",
    "buttonText": "Get Started"
  },
  "steps": [
    {
      "id": "step1",
      "title": "Personal Information",
      "description": "Tell us about yourself",
      "fields": [
        {
          "id": "fullName",
          "label": "Full Name",
          "type": "text",
          "placeholder": "John Doe",
          "required": true
        },
        {
          "id": "email",
          "label": "Email Address",
          "type": "email",
          "placeholder": "john@example.com",
          "required": true,
          "validationRegex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
          "validationMessage": "Please enter a valid email address"
        }
      ]
    },
    {
      "id": "step2",
      "title": "Preferences",
      "description": "Customize your experience",
      "fields": [
        {
          "id": "interests",
          "label": "What are you interested in?",
          "type": "checkbox-group",
          "required": true,
          "options": [
            { "value": "tech", "label": "Technology" },
            { "value": "design", "label": "Design" },
            { "value": "business", "label": "Business" }
          ],
          "allowOther": true
        }
      ]
    }
  ],
  "completion": {
    "title": "All Done!",
    "message": "Thank you for completing the form.",
    "buttonText": "Start Over"
  }
}

3. Save/Load Progress

import React, { useRef } from 'react';
import { MultiStepForm, MultiStepFormHandle, FormConfig } from '@yourscope/react-multi-step-form';

function App() {
  const formRef = useRef<MultiStepFormHandle>(null);
  const formConfig: FormConfig = /* your config */;

  const saveProgress = () => {
    if (formRef.current) {
      const state = formRef.current.getState();
      localStorage.setItem('formProgress', JSON.stringify(state));
      alert('Progress saved!');
    }
  };

  const loadProgress = () => {
    const saved = localStorage.getItem('formProgress');
    if (saved && formRef.current) {
      formRef.current.restoreState(JSON.parse(saved));
      alert('Progress restored!');
    }
  };

  return (
    <>
      <MultiStepForm
        ref={formRef}
        config={formConfig}
        onSubmit={(data) => console.log(data)}
      />
      <button onClick={saveProgress}>Save</button>
      <button onClick={loadProgress}>Load</button>
    </>
  );
}

API Reference

Components

<MultiStepForm />

The main form component.

Props:

• config: FormConfig - The form configuration object (required)
• onSubmit?: (formData: FormData) => void - Callback when form is submitted

Ref Methods (via MultiStepFormHandle):

• getState(): FormState - Get current form state
• restoreState(state: FormState): void - Restore saved state

Types

interface FormConfig {
  formId: string;
  title: string;
  welcome?: WelcomeConfig;
  steps: FormStep[];
  completion?: CompletionConfig;
}

interface FormStep {
  id: string;
  title: string;
  description?: string;
  fields: FormField[];
}

interface FormField {
  id: string;
  label: string;
  type: FormFieldType;
  placeholder?: string;
  required?: boolean;
  validationRegex?: string;
  validationMessage?: string;
  options?: Array<{ value: string; label: string }>;
  allowOther?: boolean;
}

type FormFieldType =
  | 'text'
  | 'email'
  | 'password'
  | 'tel'
  | 'number'
  | 'textarea'
  | 'select'
  | 'radio-group'
  | 'checkbox-group';

type FormData = Record<string, string>;

Field Types

All radio-group and checkbox-group fields support allowOther: true to add an "Other" option with a text input.

Styling

This library uses Tailwind CSS. Make sure Tailwind is configured in your project:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

Update your tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}",
    "./node_modules/@yourscope/react-multi-step-form/dist/**/*.js"
  ],
  // ... rest of config
}

Examples

Check out the examples directory for a full working demo.

To run the demo locally:

git clone https://github.com/octopuslabs-fl/Generic-Form-Builder.git
cd Generic-Form-Builder
npm install
npm run dev

Development

Building the Library

# Build for production
npm run build:lib

# This generates:
# - dist/index.mjs (ES module)
# - dist/index.cjs (CommonJS)
# - dist/index.d.ts (TypeScript types)

Running the Demo

npm run dev

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © [Your Name]

Support

• 🐛 Report issues
• 💬 Discussions
• 📖 Documentation

Note: Before publishing to npm, remember to:

1. Update package name in package.json (remove @yourscope/ or use your actual scope)
2. Add your author information
3. Update repository URLs
4. Add a LICENSE file
5. Test the build with npm run build:lib