GMS Form Builder

A dynamic, multi-step form builder library for React, driven by a flexible JSON schema. Built with TypeScript, Tailwind CSS, and Framer Motion for beautiful, animated forms.

Table of Contents

• Features
• Installation
• Setup
• Usage
• Props
  • schema
  • onSubmit
  • themeColor
  • fontFamily
  • containerStyle
  • fieldStyle
• The FormSchema Object
  • Top-Level Properties
  • Single-Page vs. Multi-Step Forms
• Field Definitions
  • Base Field Properties
  • Input Fields
    • Text
    • Textarea
    • Dropdown
    • Checkbox
    • Number
    • Date
    • File
  • Content Elements
    • Heading
    • Paragraph
    • Image
• Advanced Features
  • Multi-Step Forms
  • Conditional Logic
• Customization
  • Theming
  • Styling Individual Elements
• Development
• License

Features

• JSON-Driven: Define complex forms with a simple and intuitive JSON schema.
• Multi-Step Forms: Easily create wizard-like forms with a built-in animated stepper.
• Conditional Logic: Show or hide fields based on user input for dynamic forms.
• Rich Field Types: A wide range of inputs and static content elements.
• Validation: Built-in support for required fields.
• Theming: Easily customize colors and fonts to match your brand.
• Animations: Smooth transitions powered by Framer Motion.
• Fully Typed: Written in TypeScript for excellent developer experience.

Installation

npm install gms-form-builder
# or
yarn add gms-form-builder

Setup

To use the library, you need to import the component and its stylesheet, and configure your tailwind.config.js to scan the library's classes.

1. Install Peer Dependencies:

   npm install react react-dom framer-motion

2. Import Styles: Import the CSS file in your main application entry point (e.g., App.tsx or main.tsx).

   import 'gms-form-builder/dist/index.css';

3. Update tailwind.config.js: Add the path to gms-form-builder's components in your content array. This allows Tailwind to purge unused styles correctly.

   // tailwind.config.js
   module.exports = {
     content: [
       './src/**/*.{js,ts,jsx,tsx}',
       './node_modules/gms-form-builder/dist/**/*.mjs', // Add this line
     ],
     theme: {
       extend: {
          colors: {
           primary: 'var(--theme-color, #4F46E5)', // Use CSS variable for theme color
         }
       },
     },
     plugins: [],
   };

   Note: The library uses a CSS variable --theme-color for its primary color. You can override this for more advanced theming.

Usage

Here is a basic example of how to use the FormBuilder.

import { FormBuilder, FormSchema } from "gms-form-builder";
import 'gms-form-builder/dist/index.css';

const myFormSchema: FormSchema = {
  title: "User Registration",
  description: "Please fill out the form to create an account.",
  fields: [
    {
      type: "text",
      name: "username",
      label: "Username",
      required: true,
      placeholder: "Enter your username",
    },
    {
      type: "checkbox",
      name: "isSubscribed",
      label: "Subscribe to our newsletter?",
    },
    {
      type: "text",
      name: "email",
      label: "Email Address",
      required: true,
      placeholder: "[email protected]",
      conditional: {
        field: "isSubscribed",
        value: true
      }
    },
  ],
};

function App() {
  const handleSubmit = (values: Record<string, unknown>) => {
    console.log("Form Submitted:", values);
    alert(JSON.stringify(values, null, 2));
  };

  return (
    <div className="max-w-2xl mx-auto p-8">
      <FormBuilder schema={myFormSchema} onSubmit={handleSubmit} />
    </div>
  );
}

export default App;

FormBuilder Props

The FormBuilder component accepts the following props:

schema: FormSchema

(Required)

The JSON object that defines the entire form structure, including its steps and fields. See The FormSchema Object for a detailed breakdown.

onSubmit: (values: Record<string, unknown>) => void | Promise<void>

A callback function that is executed when the form is successfully submitted. It receives an object containing all the form values, where keys are the name of each field. This function can be asynchronous.

themeColor: string

• Default: '#4F46E5'

Sets the primary color for the form, affecting buttons, focus rings, and other accent elements. This is passed as a CSS variable (--theme-color).

fontFamily: string

• Default: 'sans-serif'

Sets the font-family for the entire form component.

containerStyle: React.CSSProperties

An object of inline styles to apply to the main form container.

fieldStyle: React.CSSProperties

An object of inline styles to apply to the wrapper of each individual field.

The FormSchema Object

This object is the blueprint for your form.

Top-Level Properties

| Property | Type | Description | | :------------ | :--------- | :-------------------------------------------------------------------------- | | title | string | (Optional) A title displayed at the top of the form. | | description | string | (Optional) A short description displayed below the title. | | steps | FormStep[] | An array of step objects for creating a multi-step form. See FormStep. | | fields | Field[] | An array of field objects. Used if steps is not provided for a single-page form. |

FormStep Object

Used within the steps array.

| Property | Type | Description | | :------- | :-------- | :----------------------------------------------- | | title | string | The title of the step, shown in the stepper UI. | | fields | Field[] | An array of field objects for this specific step. |

Single-Page vs. Multi-Step Forms

• To create a single-page form, provide a fields array directly in the schema.
• To create a multi-step form, provide a steps array. The library will automatically render a stepper and handle navigation.

Field Definitions

Each object in a fields array defines a component to be rendered in the form.

Base Field Properties

These properties are available on all field types, though some may be optional for content elements.

| Property | Type | Description | | :------------ | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | name | string | A unique identifier for the field. This becomes the key in the final form values object. | | type | FieldType | The type of field to render. See below for all available types. | | label | string | The display label for the field. | | required | boolean | (Optional) If true, the field must be filled out before proceeding or submitting. Default: false. | | icon | React.ReactNode | (Optional) A React node (e.g., an SVG icon) to display with the input. | | conditional | object | (Optional) An object to control field visibility. See Conditional Logic. |

Input Fields

These fields collect data from the user.

Text

A standard text input.

• type: "text"
• placeholder: string (Optional) - Placeholder text for the input.

Textarea

A multi-line text input.

• type: "textarea"
• placeholder: string (Optional) - Placeholder text.
• rows: number (Optional) - The visible number of lines in the text area. Default: 3.

Dropdown

A select dropdown.

• type: "dropdown"
• options: string[] - An array of strings to populate the dropdown options.

Checkbox

A checkbox input.

• type: "checkbox"
• The label is rendered next to the checkbox.

Number

An input for numerical values.

• type: "number"
• placeholder: string (Optional) - Placeholder text.

Date

A date picker input. The browser's native date picker is used.

• type: "date"

File

A file input.

• type: "file"

Content Elements

These fields display static content and do not collect data.

Heading

• type: "heading"
• text: string - The content of the heading.
• level: 1 | 2 | 3 | 4 | 5 | 6 (Optional) - The heading level (e.g., 1 for <h1>). Default: 2.

Paragraph

• type: "paragraph"
• text: string - The content of the paragraph.

Image

• type: "image" -src: string` - The URL of the image.
• alt: string (Optional) - Alt text for the image.
• caption: string (Optional) - A caption displayed below the image.

Advanced Features

Multi-Step Forms

To create a multi-step form, define a steps array in your schema. Each object in the array represents a step and contains a title and its own fields array.

Example:

{
  "title": "Onboarding",
  "steps": [
    {
      "title": "Personal Info",
      "fields": [
        { "type": "text", "name": "firstName", "label": "First Name" }
      ]
    },
    {
      "title": "Account Details",
      "fields": [
        { "type": "text", "name": "email", "label": "Email" }
      ]
    }
  ]
}

Conditional Logic

You can show or hide a field based on the value of another field. Add the conditional property to any field you want to control.

• conditional.field: string - The name of the field to check.
• conditional.value: any - The value the trigger field must have for this field to be visible.

Example: A text field for "Other" reason appears only when "Other" is selected in a dropdown.

{
  "fields": [
    {
      "type": "dropdown",
      "name": "reason",
      "label": "Reason for Contact",
      "options": ["Question", "Feedback", "Other"]
    },
    {
      "type": "textarea",
      "name": "otherReason",
      "label": "Please specify",
      "conditional": {
        "field": "reason",
        "value": "Other"
      }
    }
  ]
}

Customization

Theming

The easiest way to theme the form is by using the themeColor prop. For more advanced control, you can override the CSS variables and Tailwind classes in your own project.

Styling Individual Elements

Use the containerStyle and fieldStyle props for quick inline style adjustments. For deeper changes, you can target the library's classes in your own CSS. It's recommended to wrap the FormBuilder in a container with a unique ID to scope your overrides and avoid conflicts.

/* Your custom CSS file */
#my-form-wrapper .gms-form-builder-container {
  border: 2px solid #ccc;
}