@lims/form-builder

A powerful, reusable React form builder that generates dynamic forms from JSON configurations with Formik integration and Yup validation.

Features

• JSON-driven: Define forms using JSON configuration
• Type-safe: Full TypeScript support
• Validation: Automatic Yup validation schema generation
• Responsive: Built-in Material-UI Grid2 layout
• Field Types: TextField, SelectField, AutocompleteField, DatePicker
• Conditional Rendering: Show/hide fields based on other field values
• Tree-shakeable: Optimized ESM and CJS builds
• React 18/19 Compatible: Works with both React 18 and React 19

Installation

npm install @lims/form-builder

or

yarn add @lims/form-builder

or

pnpm add @lims/form-builder

Peer Dependencies

This package requires the following peer dependencies:

npm install @mui/material @mui/x-date-pickers dayjs formik yup react react-dom

Quick Start

1. Basic Usage

import { FormBuilder, FormBuilderConfig } from '@lims/form-builder';

const formConfig: FormBuilderConfig = {
  formConfig: {
    formId: 'my-form',
    submitLabel: 'Submit',
    gridSpacing: 2
  },
  fields: [
    {
      uiComponentId: 'TextField',
      name: 'email',
      id: 'email',
      label: 'Email Address',
      type: 'email',
      required: true,
      validation: {
        type: 'email',
        rules: ['required', 'email']
      }
    }
  ]
};

function MyForm() {
  const handleSubmit = async (values: any) => {
    console.log('Form values:', values);
    // Process form data
  };

  return (
    <FormBuilder
      config={formConfig}
      onSubmit={handleSubmit}
      onCancel={() => console.log('Cancelled')}
    />
  );
}

2. JSON Configuration Structure

{
  "formConfig": {
    "formId": "my-form",
    "title": "My Form",
    "submitLabel": "Submit",
    "cancelLabel": "Cancel",
    "showCancelButton": true,
    "gridSpacing": 2
  },
  "fields": [
    {
      "uiComponentId": "TextField",
      "name": "email",
      "id": "email",
      "label": "Email Address",
      "placeholder": "Enter email",
      "type": "email",
      "required": true,
      "defaultValue": "",
      "fullWidth": true,
      "variant": "outlined",
      "size": { "xs": 12, "md": 6 },
      "validation": {
        "type": "email",
        "rules": ["required", "email"],
        "messages": {
          "required": "Email is required",
          "email": "Please enter a valid email"
        }
      }
    }
  ]
}

Field Types

TextField

Standard text input with support for various HTML input types.

{
  "uiComponentId": "TextField",
  "name": "username",
  "label": "Username",
  "type": "text",
  "multiline": false,
  "rows": 1
}

SelectField

Dropdown selection field.

{
  "uiComponentId": "SelectField",
  "name": "country",
  "label": "Country",
  "options": [
    { "label": "United States", "value": "us" },
    { "label": "Canada", "value": "ca" }
  ]
}

AutocompleteField

Autocomplete with search and multi-select support.

{
  "uiComponentId": "AutocompleteField",
  "name": "skills",
  "label": "Skills",
  "multiple": true,
  "freeSolo": false,
  "options": [
    { "label": "JavaScript", "value": "js" },
    { "label": "Python", "value": "py" }
  ]
}

DatePicker

Date selection field.

{
  "uiComponentId": "DatePicker",
  "name": "birthDate",
  "label": "Date of Birth",
  "type": "date",
  "minDate": "1900-01-01",
  "maxDate": "2023-12-31",
  "disableFuture": true
}

Validation Rules

The form builder supports these validation rules:

• required - Field is required
• min:X - Minimum length/value
• max:X - Maximum length/value
• email - Must be valid email
• url - Must be valid URL
• matches:pattern:flags - Regex pattern matching
• oneOf:val1,val2 - Must be one of specified values
• length:X - Exact length
• positive - Must be positive number
• negative - Must be negative number
• integer - Must be integer

Example with Multiple Rules

{
  "validation": {
    "type": "string",
    "rules": ["required", "min:3", "max:50", "matches:^[a-zA-Z]+$"],
    "messages": {
      "required": "This field is required",
      "min": "Must be at least 3 characters",
      "max": "Cannot exceed 50 characters",
      "matches": "Only letters are allowed"
    }
  }
}

Responsive Grid Sizing

Use Material-UI Grid2 breakpoints for responsive layouts:

{
  "size": {
    "xs": 12,   // Full width on mobile
    "sm": 6,    // Half width on small screens
    "md": 4,    // Third width on medium screens
    "lg": 3     // Quarter width on large screens
  }
}

Conditional Rendering

Show/hide fields based on other field values:

{
  "name": "otherCountry",
  "label": "Specify Country",
  "conditionalRender": {
    "field": "country",
    "operator": "equals",
    "value": "other"
  }
}

Supported Operators:

• equals - Field value equals specified value
• notEquals - Field value does not equal
• includes - Array includes value
• notIncludes - Array does not include value
• greaterThan - Numeric comparison
• lessThan - Numeric comparison

Advanced Usage

With Initial Values

<FormBuilder
  config={formConfig}
  onSubmit={handleSubmit}
  initialValues={{ email: '[email protected]' }}
  enableReinitialize={true}
/>

Programmatic Form Access

import { buildValidationSchema, buildInitialValues } from '@lims/form-builder';

const schema = buildValidationSchema(fields);
const initialValues = buildInitialValues(fields);

API Reference

Components

FormBuilder

The main component for rendering dynamic forms.

Props:

• config: FormBuilderConfig - Form configuration object
• onSubmit: (values: any) => void | Promise<void> - Submit handler
• onCancel?: () => void - Cancel handler (optional)
• initialValues?: { [key: string]: any } - Initial form values (optional)
• enableReinitialize?: boolean - Enable Formik reinitialization (default: false)

Field Components

Individual field components are also exported if you need them separately:

• FormTextField
• FormSelectField
• FormAutocompleteField
• FormDatePicker

Type Definitions

All types are exported for TypeScript support:

import type {
  FormBuilderConfig,
  FormConfig,
  FieldConfig,
  ValidationRule,
  OptionType,
  GridSize,
  ConditionalRender,
  FieldType,
  UIComponentType,
  ValidationType
} from '@lims/form-builder';

Utility Functions

buildValidationSchema(fields: FieldConfig[])

Generates a Yup validation schema from field configurations.

buildInitialValues(fields: FieldConfig[])

Extracts initial values from field configurations.

TypeScript Support

This package is written in TypeScript and includes type definitions. You get full IntelliSense and type checking out of the box.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

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

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please use the GitHub Issues page.