@matthew.ngo/react-dynamic-form v0.0.37

@matthew.ngo/react-dynamic-form

@matthew.ngo/react-dynamic-form is a powerful and flexible React library for creating dynamic forms based on a configuration object. It leverages react-hook-form for form handling and yup for validation, offering a streamlined and efficient way to build complex forms with minimal code. It also supports conditional fields, custom inputs, and theming with styled-components.

Demo

View the live demo here: https://maemreyo.github.io/react-dynamic-form/

Features

• Dynamic Form Generation: Create forms from a simple JSON configuration.
• react-hook-form Integration: Utilizes react-hook-form for efficient form state management.
• yup Validation: Supports schema-based validation using yup.
• Conditional Fields: Show or hide fields based on other field values.
• Custom Inputs: Easily integrate your own custom input components.
• Theming: Customize the look and feel with styled-components.
• Layout Options: Supports flex and grid layouts.
• Auto Save: Option to automatically save form data at intervals.
• Local Storage: Persist form data in local storage.
• Debounced onChange: Provides a debounced onChange callback.
• Built-in Input Types: Supports a wide range of input types:
  • text
  • number
  • checkbox
  • select
  • textarea
  • email
  • password
  • tel
  • url
  • radio
  • date
  • switch
  • time
  • datetime-local
  • combobox
• Highly Customizable
• Production Ready
• Basic test coverage

Installation

yarn add @matthew.ngo/react-dynamic-form react-hook-form yup @hookform/resolvers styled-components

or

npm install @matthew.ngo/react-dynamic-form react-hook-form yup @hookform/resolvers styled-components

Usage

Basic Example

import React from 'react';
import { DynamicForm, DynamicFormProps } from '@matthew.ngo/react-dynamic-form';

const basicFormConfig: DynamicFormProps['config'] = {
  firstName: {
    type: 'text',
    label: 'First Name',
    defaultValue: 'John',
    validation: {
      required: { value: true, message: 'This field is required' },
    },
  },
  lastName: {
    type: 'text',
    label: 'Last Name',
    defaultValue: 'Doe',
  },
  email: {
    type: 'email',
    label: 'Email',
    validation: {
      required: { value: true, message: 'This field is required' },
      pattern: {
        value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i,
        message: 'Invalid email address',
      },
    },
  },
};

const App: React.FC = () => {
  const handleSubmit = (data: any) => {
    console.log(data);
  };

  return (
    <div>
      <DynamicForm config={basicFormConfig} onSubmit={handleSubmit} />
    </div>
  );
};

export default App;

Advanced Example

import React from 'react';
import { DynamicForm, DynamicFormProps } from '@matthew.ngo/react-dynamic-form';
import { FlexLayout } from '@matthew.ngo/react-dynamic-form';

const advancedFormConfig: DynamicFormProps['config'] = {
  firstName: {
    label: 'First Name',
    type: 'text',
    defaultValue: 'John',
    validation: {
      required: { value: true, message: 'This field is required' },
    },
    classNameConfig: {
      input: 'border border-gray-400 p-2 rounded w-full',
      label: 'block text-gray-700 text-sm font-bold mb-2',
    },
  },
  subscribe: {
    label: 'Subscribe to newsletter?',
    type: 'checkbox',
    defaultValue: true,
    classNameConfig: {
      checkboxInput: 'mr-2 leading-tight',
      label: 'block text-gray-700 text-sm font-bold mb-2',
    },
  },
  country: {
    label: 'Country',
    type: 'select',
    defaultValue: 'US',
    options: [
      { value: 'US', label: 'United States' },
      { value: 'CA', label: 'Canada' },
      { value: 'UK', label: 'United Kingdom' },
    ],
    classNameConfig: {
      select: 'border border-gray-400 p-2 rounded w-full',
      label: 'block text-gray-700 text-sm font-bold mb-2',
    },
  },
  gender: {
    label: 'Gender',
    type: 'radio',
    defaultValue: 'male',
    options: [
      { value: 'male', label: 'Male' },
      { value: 'female', label: 'Female' },
      { value: 'other', label: 'Other' },
    ],
    classNameConfig: {
      radioGroup: 'flex items-center',
      radioLabel: 'mr-4',
      radioButton: 'mr-1',
      label: 'block text-gray-700 text-sm font-bold mb-2',
    },
  },
  dynamicField: {
    label: 'Dynamic Field',
    type: 'text',
    defaultValue: '',
    conditional: {
      when: 'firstName',
      operator: 'is',
      value: 'ShowDynamic',
      fields: ['dynamicField'],
    },
    classNameConfig: {
      input: 'border border-gray-400 p-2 rounded w-full',
      label: 'block text-gray-700 text-sm font-bold mb-2',
    },
  },
  asyncEmail: {
    label: 'Async Email Validation',
    type: 'email',
    validation: {
      required: { value: true, message: 'This field is required' },
      validate: async (value: string): Promise<any> => {
        // Simulate an async API call
        const isValid = await new Promise<boolean>((resolve) => {
          setTimeout(() => {
            resolve(value !== 'test@example.com');
          }, 1000);
        });
        return isValid || 'Email already exists (async check)';
      },
    },
    classNameConfig: {
      input: 'border border-gray-400 p-2 rounded w-full',
      label: 'block text-gray-700 text-sm font-bold mb-2',
      errorMessage: 'text-red-500 text-xs italic',
    },
  },
};

const App: React.FC = () => {
  const handleSubmit = (data: any) => {
    console.log(data);
    alert(JSON.stringify(data));
  };

  return (
    <DynamicForm
      config={advancedFormConfig}
      renderLayout={({ children, ...rest }) => (
        <FlexLayout {...rest}>{children}</FlexLayout>
      )}
      formClassNameConfig={{
        formContainer: 'p-6 border border-gray-300 rounded-md',
        inputWrapper: 'mb-4',
        errorMessage: 'text-red-600',
        button:
          'bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded w-full',
      }}
      autoSave={{
        interval: 3000,
        save: (data) => console.log('Auto-saving:', data),
      }}
      enableLocalStorage={true}
      resetOnSubmit={true}
      focusFirstError={true}
      debounceOnChange={300}
      onSubmit={handleSubmit}
      onChange={(data) => console.log('Debounced change:', data)}
      onFormReady={(form) => {
        console.log('Form is ready:', form);
      }}
      showSubmitButton={true}
      showInlineError={true}
      showErrorSummary={true}
    />
  );
};

export default App;

Props

The DynamicForm component accepts the following props:

FormConfig

The FormConfig object defines the structure and behavior of the form. Each key in the object represents a field in the form, and the value is a FieldConfig object that defines the field's properties.

FieldConfig

InputType

Supported input types:

• text
• number
• checkbox
• select
• textarea
• email
• password
• tel
• url
• radio
• date
• switch
• time
• datetime-local
• combobox
• custom

ValidationConfig

Condition

ComparisonOperator

Supported comparison operators:

• is
• isNot
• greaterThan
• lessThan
• greaterThanOrEqual
• lessThanOrEqual
• contains
• startsWith
• endsWith
• custom

FormClassNameConfig

FieldClassNameConfig

Same as FormClassNameConfig, but applies to individual fields. FieldClassNameConfig will override FormClassNameConfig for that specific field.

Validation

You can define validation rules for each field in the validation property of the FieldConfig object. The validation property can contain the following validation rules:

• required: Whether the field is required.
• minLength: The minimum length of the field's value.
• maxLength: The maximum length of the field's value.
• min: The minimum value of the field (for number, date).
• max: The maximum value of the field (for number, date).
• pattern: A regular expression that the field's value must match.
• validate: A custom validation function.

Custom Validation Messages

You can provide custom validation messages for each field by using the validationMessages property in the FieldConfig object. You can also provide global custom validation messages for the whole form by using the validationMessages prop in the DynamicForm component. FieldConfig.validationMessages will override DynamicForm.validationMessages for that specific field.

// Example usage
const formConfig: DynamicFormProps['config'] = {
  email: {
    type: 'email',
    label: 'Email',
    validation: {
      required: { value: true, message: 'This field is required' },
      pattern: {
        value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i,
        message: 'Invalid email address',
      },
    },
    validationMessages: {
      required: 'You must enter an email address.', // Override required message for this field
      pattern: ({ value }) => `${value} is not a valid email address.`, // Dynamic message based on input value
    },
  },
};

// Global validation messages
const validationMessages: ValidationMessages = {
  required: 'This is a globally defined required message',
};

Validation Messages Interface

interface ValidationMessages {
  [key: string]:
    | string // Static message
    | ((values: {
        label?: string;
        value: any;
        error: any;
        config: FieldConfig;
      }) => string); // Dynamic message function
}

Custom Validation Function

The validate function receives two arguments:

• value: The current value of the field.
• formValues: The current values of all fields in the form.

The function should return a string if validation fails (the error message), or undefined if validation passes. You can also return a Promise that resolves to a string or undefined for asynchronous validation.

// Example custom validation function that checks if an email is already taken
const validateEmailNotTaken = async (value: string) => {
  const isTaken = await checkIfEmailExists(value); // Assume this function makes an API call
  if (isTaken) {
    return 'Email already taken';
  }
  return undefined;
};

// Example usage in a field configuration
const formConfig: DynamicFormProps['config'] = {
  email: {
    type: 'email',
    label: 'Email',
    validation: {
      validate: validateEmailNotTaken,
    },
  },
};

Custom Inputs

You can create your own custom input components and use them in the form. To do this, pass a customInputs prop to the DynamicForm component. The customInputs prop is an object where the keys are the input types and the values are the custom components.

import React from 'react';
import {
  DynamicForm,
  DynamicFormProps,
  CustomInputProps,
} from '@matthew.ngo/react-dynamic-form';

// Example custom input component
const MyCustomInput: React.FC<CustomInputProps> = ({
  fieldConfig,
  formClassNameConfig,
  field,
  onChange,
  value,
}) => {
  return (
    <div>
      <label htmlFor={fieldConfig.id}>{fieldConfig.label}</label>
      <input
        id={fieldConfig.id}
        type="text"
        value={value || ''}
        onChange={(e) => onChange(e.target.value)}
        className={formClassNameConfig?.input}
      />
      {/* You can add your own error handling here */}
    </div>
  );
};

// Example usage of custom input
const myFormConfig: DynamicFormProps['config'] = {
  customField: {
    type: 'custom',
    label: 'My Custom Field',
    component: MyCustomInput, // Specify the custom component here
  },
};

const App: React.FC = () => {
  const handleSubmit = (data: any) => {
    console.log(data);
  };

  return (
    <DynamicForm
      config={myFormConfig}
      onSubmit={handleSubmit}
      customInputs={{
        custom: MyCustomInput, // Register the custom input type
      }}
    />
  );
};

export default App;

Theming

You can customize the look and feel of the form by providing a custom theme object to the DynamicForm component via the theme prop. The theme object should follow the styled-components DefaultTheme interface.

import React from 'react';
import {
  DynamicForm,
  DynamicFormProps,
  defaultTheme,
} from '@matthew.ngo/react-dynamic-form';
import { ThemeProvider } from 'styled-components';

const myTheme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    primary: 'blue',
  },
};

const myFormConfig: DynamicFormProps['config'] = {
  firstName: {
    type: 'text',
    label: 'First Name',
  },
};

const App: React.FC = () => {
  return (
    <ThemeProvider theme={myTheme}>
      <DynamicForm config={myFormConfig} />
    </ThemeProvider>
  );
};

export default App;

Contributing

Contributions are welcome! Please read the contributing guidelines (TODO: create this file later) for details on how to contribute.

License

This project is licensed under the MIT License - see the LICENSE file for details.