@etherisc/react-json-form-builder

React JSON Form Builder

A React component library for building beautiful forms using JSON Schema with Tailwind CSS styling.

Features

• 🎨 Beautiful, responsive forms with Tailwind CSS
• 📝 JSON Schema validation using @rjsf/validator-ajv8
• 🎯 Customizable form layouts with UI Schema
• 🔧 Rich form controls (text, email, number, date, select, etc.)
• 🎛️ Custom button support
• 🎭 Flexible styling options

Installation

npm install @etherisc/react-json-form-builder

Make sure you have the peer dependencies installed:

npm install react react-dom tailwindcss

Usage

1. Import the FormBuilder component:

import { FormBuilder } from '@etherisc/react-json-form-builder';

2. Use it in your React component:

function MyForm() {
  const schema = {
    type: 'object',
    properties: {
      firstName: { type: 'string', title: 'First Name' },
      email: { type: 'string', format: 'email', title: 'Email' }
    },
    required: ['firstName', 'email']
  };

  const uiSchema = {
    'ui:options': {
      columns: 2 // Display fields in 2 columns
    }
  };

  const handleSubmit = ({ formData }) => {
    console.log('Form submitted:', formData);
  };

  return (
    <FormBuilder
      schema={schema}
      uiSchema={uiSchema}
      onSubmit={handleSubmit}
      // Optional custom buttons
      customButtons={[
        {
          text: 'Cancel',
          onClick: () => console.log('Cancelled'),
          className: 'bg-gray-500 hover:bg-gray-600 text-white font-bold py-2 px-4 rounded'
        }
      ]}
    />
  );
}

Props

Prop	Type	Description
schema	object	JSON Schema object defining the form structure
uiSchema	object	UI Schema for customizing layout and appearance
formData	object	Initial form data
onChange	function	Callback when form values change
onSubmit	function	Callback when form is submitted
onError	function	Callback when validation errors occur
buttons	object	Customize default buttons (submit)
customButtons	array	Add additional buttons to the form
className	string	Additional CSS classes for the form
showErrorList	false | "top" | "bottom"	Whether and where to show validation errors
noHtml5Validate	boolean	Whether to disable HTML5 validation

Customizing Buttons

You can customize the submit button or hide it completely:

// Custom submit button text and style
<FormBuilder
  schema={schema}
  buttons={{
    submit: {
      text: 'Save',
      className: 'bg-green-500 hover:bg-green-600 text-white font-bold py-2 px-4 rounded'
    }
  }}
/>

// Hide the submit button
<FormBuilder
  schema={schema}
  buttons={{ submit: null }}
/>

Error Handling

You can control how validation errors are displayed:

// Show errors at the top of the form
<FormBuilder
  schema={schema}
  showErrorList="top"
/>

// Show errors at the bottom of the form
<FormBuilder
  schema={schema}
  showErrorList="bottom"
/>

// Don't show error list
<FormBuilder
  schema={schema}
  showErrorList={false}
/>

UI Schema Options

The UI Schema supports various options for customizing the form layout:

const uiSchema = {
  'ui:options': {
    columns: 2 // Number of columns in the form grid
  },
  'ui:order': ['field1', 'field2'], // Custom field order
  fieldName: {
    'ui:widget': 'textarea', // Custom widget for a field
    'ui:options': {
      rows: 5 // Widget-specific options
    }
  }
};

Development

This project follows the GitFlow branching model:

Branches

• main - Production releases
• develop - Development branch, source for feature branches
• feature/* - New features
• bugfix/* - Bug fixes
• release/* - Release preparation
• hotfix/* - Urgent fixes for production

Development Workflow

1. Create a feature branch from develop:

   git checkout -b feature/your-feature develop

2. Make your changes and commit using conventional commits:

   git commit -m "feat: add new feature"
   git commit -m "fix: resolve issue"

3. Push your feature branch:

   git push origin feature/your-feature

4. Create a Pull Request to merge into develop

5. After review and approval, merge using squash merge

Release Process

1. Create a release branch:

   git checkout -b release/1.0.0 develop

2. Version bump and final testing

3. Merge into main AND develop:

   git checkout main
   git merge --no-ff release/1.0.0
   git tag -a v1.0.0
   git checkout develop
   git merge --no-ff release/1.0.0

Styling

The library uses Tailwind CSS for styling. You can customize the appearance by:

1. Overriding the default classes through the className prop
2. Customizing the Tailwind configuration
3. Using custom CSS classes in your UI Schema

Contributing

Contributions are welcome! Please follow our development workflow and submit your Pull Requests against the develop branch.

License

MIT