MUI Smart Form Builder

A powerful and flexible React component for dynamically rendering Material-UI forms from JSON configuration with Formik integration.

Features

• 🎯 Formik Integration: Seamless integration with Formik for form state management
• 🎨 Material-UI Components: Built with MUI components for consistent design
• 📱 Responsive Layout: Grid-based responsive layout system
• 🔧 Flexible Configuration: JSON-driven form configuration
• 🎭 Custom Rendering: Support for custom field renderers
• 🔍 Dynamic Search: Autocomplete fields with async search capabilities
• 📝 Rich Field Types: Support for 15+ field types
• 💪 TypeScript: Full TypeScript support with comprehensive types
• 🌳 Tree Shakeable: Optimized for tree shaking

Installation

npm install mui-smart-form-builder

Peer Dependencies

npm install @mui/material @emotion/react @emotion/styled formik

Optional Dependencies (for date/time fields)

npm install @mui/x-date-pickers dayjs

Note: When using date/time fields, you must wrap your app with LocalizationProvider:

import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';

<LocalizationProvider dateAdapter={AdapterDayjs}>
  <YourApp />
</LocalizationProvider>

npm install mui-smart-form-builder

# Peer dependencies (if not already installed)
npm install react react-dom @mui/material @emotion/react @emotion/styled formik

For date/time pickers, also install:

npm install @mui/x-date-pickers dayjs

Quick Start

import React from 'react';
import { useFormik } from 'formik';
import { SmartFormBuilder } from 'mui-smart-form-builder';

const MyForm = () => {
  const formik = useFormik({
    initialValues: {
      firstName: '',
      lastName: '',
      email: '',
      age: 0,
      gender: '',
      newsletter: false
    },
    onSubmit: (values) => {
      console.log('Form submitted:', values);
    }
  });

  const fields = [
    {
      name: 'firstName',
      label: 'First Name',
      type: 'text',
      required: true,
      grid: { xs: 12, md: 6 }
    },
    {
      name: 'lastName',
      label: 'Last Name',
      type: 'text',
      required: true,
      grid: { xs: 12, md: 6 }
    },
    {
      name: 'email',
      label: 'Email',
      type: 'text',
      placeholder: 'Enter your email',
      grid: { xs: 12 }
    },
    {
      name: 'age',
      label: 'Age',
      type: 'number',
      min: 0,
      max: 120,
      grid: { xs: 12, md: 6 }
    },
    {
      name: 'gender',
      label: 'Gender',
      type: 'radio',
      options: [
        { label: 'Male', value: 'M' },
        { label: 'Female', value: 'F' },
        { label: 'Other', value: 'O' }
      ],
      grid: { xs: 12, md: 6 }
    },
    {
      name: 'newsletter',
      label: 'Subscribe to newsletter',
      type: 'checkbox',
      grid: { xs: 12 }
    }
  ];

  const buttons = [
    {
      label: 'Reset',
      variant: 'outlined',
      onClick: (formik) => formik.resetForm()
    },
    {
      label: 'Submit',
      variant: 'contained',
      type: 'submit'
    }
  ];

  return (
    <SmartFormBuilder
      formik={formik}
      title="User Registration Form"
      fields={fields}
      buttons={buttons}
      gridSpacing={2}
    />
  );
};

export default MyForm;

Supported Field Types

Text Fields

• text - Standard text input
• textarea - Multi-line text input
• number - Numeric input with min/max/step support
• password - Password input

Selection Fields

• checkbox - Single checkbox
• multiCheckbox - Multiple checkboxes
• radio - Radio button group
• select - Dropdown select (single/multiple)
• autocomplete - Autocomplete with async search

Date/Time Fields

• date - Date picker
• time - Time picker
• dateTime - Date and time picker

Interactive Fields

• switch - Toggle switch
• slider - Range slider
• file - File upload

Layout

• empty - Empty space for layout purposes

API Reference

SmartFormBuilderProps

| Prop | Type | Required | Description | |------|------|----------|-------------| | formik | FormikProps<any> | ✅ | Formik instance | | fields | FieldConfig[] | ✅ | Array of field configurations | | buttons | ButtonConfig[] | ❌ | Form buttons configuration | | title | string | ❌ | Form title | | className | string | ❌ | CSS class name | | sx | SxProps | ❌ | MUI sx prop for styling | | gridSpacing | number | ❌ | Grid spacing (default: 2) |

FieldConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | name | string | ❌ | Field name (formik key) | | label | string | ❌ | Field label | | type | FieldType | ✅ | Field type | | placeholder | string | ❌ | Placeholder text | | options | FieldOption[] or string[] | ❌ | Options for select/radio/checkbox | | grid | GridBreakpoint | ❌ | Grid responsive breakpoints | | required | boolean | ❌ | Required field validation | | variant | 'outlined' | 'filled' | 'standard' | ❌ | MUI variant | | muiProps | Record<string, any> | ❌ | Additional MUI props | | onChange | (value: any, formik: FormikProps) => void | ❌ | Custom change handler | | onSearch | (searchTerm: string) => Promise<FieldOption[]> | ❌ | Async search for autocomplete | | render | (props) => ReactNode | ❌ | Custom render function |

Field-specific Properties

| Property | Applicable Types | Description | |----------|------------------|-------------| | min, max, step | number, slider | Numeric constraints | | marks | slider | Show marks on slider | | freeSolo | autocomplete | Allow free text input | | multiple | select, autocomplete | Multiple selection | | accept | file | File type filter |

ButtonConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | label | string | ✅ | Button text | | variant | 'text' | 'outlined' | 'contained' | ❌ | Button variant | | color | MUI color | ❌ | Button color | | type | 'submit' | 'button' | 'reset' | ❌ | Button type | | onClick | (formik: FormikProps) => void | ❌ | Click handler | | muiProps | Record<string, any> | ❌ | Additional MUI props |

Advanced Usage

Custom Field Rendering

const customField = {
  name: 'customField',
  type: 'text',
  render: ({ fieldProps, formik }) => (
    <CustomComponent 
      {...fieldProps}
      onCustomAction={() => {
        // Custom logic
        formik.setFieldValue('customField', 'new value');
      }}
    />
  )
};

Async Autocomplete

const asyncAutocomplete = {
  name: 'skills',
  label: 'Skills',
  type: 'autocomplete',
  freeSolo: true,
  multiple: true,
  onSearch: async (searchTerm) => {
    const response = await fetch(`/api/skills?q=${searchTerm}`);
    const data = await response.json();
    return data.map(skill => ({ label: skill.name, value: skill.id }));
  }
};

Dynamic Field Updates

const conditionalField = {
  name: 'country',
  label: 'Country',
  type: 'select',
  options: countries,
  onChange: (value, formik) => {
    // Reset state field when country changes
    formik.setFieldValue('state', '');
    
    // Fetch states for selected country
    fetchStates(value).then(states => {
      // Update form configuration dynamically
    });
  }
};

Validation

The component works seamlessly with Formik's validation. You can use Yup schema or custom validation:

import * as Yup from 'yup';

const validationSchema = Yup.object({
  firstName: Yup.string().required('First name is required'),
  email: Yup.string().email('Invalid email').required('Email is required'),
  age: Yup.number().min(18, 'Must be at least 18').required()
});

const formik = useFormik({
  initialValues,
  validationSchema,
  onSubmit: handleSubmit
});

Styling

Global Styling

<SmartFormBuilder
  formik={formik}
  fields={fields}
  sx={{
    '& .MuiTextField-root': {
      marginBottom: 2
    },
    '& .MuiFormControl-root': {
      width: '100%'
    }
  }}
/>

Per-field Styling

const styledField = {
  name: 'specialField',
  type: 'text',
  muiProps: {
    sx: { 
      backgroundColor: 'primary.light',
      '& .MuiInputBase-root': {
        borderRadius: 2
      }
    }
  }
};

Examples

See the /demo folder for a complete example application showcasing all features.

Changelog

[1.0.2] - 2025-08-10

• BREAKING: Moved @mui/x-date-pickers and dayjs from dependencies to peer dependencies
• BREAKING: Removed internal LocalizationProvider wrapper - consumers must now provide it
• Updated documentation with LocalizationProvider setup requirements
• Fixed build configuration to properly exclude peer dependencies
• Added custom icon for demo application
• Improved GitHub Pages deployment configuration

[1.0.1] - 2025-08-09

• Cleaned up build outputs from version control
• Added .gitignore for dist/ directory
• Improved rollup configuration for peer dependencies handling

[1.0.0] - 2025-08-09

• Initial release
• Complete form builder with 15+ field types
• Formik integration
• Material-UI components
• TypeScript support
• Responsive grid system
• Custom field renderers
• Async autocomplete search

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Demo

🚀 Live Demo: https://deepu9990.github.io/mui-smart-form-builder/

📦 CodeSandbox: https://codesandbox.io/s/github/deepu9990/mui-smart-form-builder/tree/main/demo

Try the interactive demo to see all field types and features in action!

License

MIT License - see the LICENSE file for details.