React JSON Schema Form Builder

The Form Builder allows you to create conditional visibility using a Parent/Dependent model, which abstracts the React JSON Schema Form dependencies feature.

How it works

• Parent: The element that controls the visibility of others.
• Dependent: The element that is hidden or shown based on the parent's state.
• Possibilities: Within the element's modal, you can create "possibilities" to define the logic.

Configuration Options

When setting up a parent, you can choose how the dependency is triggered:

1. Any value: The dependent elements appear if the parent has any value entered.
2. Specific value: The dependent elements appear only when the parent matches a specific value (allowing for multiple different scenarios/possibilities).

Visual Indicators

Dependent elements are rendered with dashed borders and an asterisk to indicate they are currently hidden and waiting for the parent's condition to be met.

The Mods object is passed to the FormBuilder component via the mods prop to customize its behavior, appearance, and available input types.

Key customization capabilities include:

• Custom Inputs: Define new input types via customFormInputs.
• UI Customization: Hide default inputs with deactivatedFormInputs, customize labels with labels, or change tooltip text with tooltipDescriptions.
• Component Overrides: Replace the "Add" button component using components.add.
• Defaults: Set default data or UI schema for new elements using newElementDefaultDataOptions or newElementDefaultUiSchema.
• Visibility: Toggle the form header using showFormHead (defaults to true).

import { FormBuilder, type Mods } from '@ginkgo-bioworks/react-json-schema-form-builder';

const myMods: Mods = {
  showFormHead: false,
  deactivatedFormInputs: ['number'],
  // ... other mod configurations
};

<FormBuilder mods={myMods} />

You can extend the FormBuilder with custom input types by defining a FormInput object and passing it into the mods property. A custom input translates abstract input types into specific JSON Schema and UI Schema configurations.

Key types for implementation:

• FormInput: The definition of the custom input.
• Match: Used in FormInput.matchIf to define when this input should be used (e.g., matching a specific type or widget).
• DataType: Valid JSON Schema types ('string' | 'number' | 'boolean' | 'integer' | 'array' | 'object' | 'null').
• CardComponent: The component rendered in the cardBody (the builder UI) or modalBody (the configuration UI).
• CardComponentProps: The props passed to these components, including parameters (the current schema/ui-schema state) and onChange (to update the state).

import type { FormInput, Match, DataType, CardComponent, CardComponentProps } from '@ginkgo-bioworks/react-json-schema-form-builder';

const myCustomInput: FormInput = {
  displayName: 'My Custom Input',
  matchIf: [{ types: ['string'], widget: 'my-widget' }],
  defaultDataSchema: { type: 'string' },
  defaultUiSchema: { 'ui:widget': 'my-widget' },
  type: 'string',
  cardBody: ({ parameters, onChange }) => (
    // Implementation of the builder UI
    <div />
  ),
  modalBody: ({ parameters, onChange }) => (
    // Implementation of the configuration modal
    <div />
  ),
};

// Usage in FormBuilder
<FormBuilder 
  mods={{ 
    customFormInputs: { myInput: myCustomInput } 
  }} 
  {...otherProps} 
/>

To provide a real-time preview of the form being built, you can pair FormBuilder with an implementation of the Form component from react-jsonschema-form (RJSF).

First, install the necessary RJSF dependencies:

npm i --save @rjsf/core @rjsf/mui @rjsf/validator-ajv8

Then, use the schema and uischema produced by FormBuilder to drive the RJSF Form component. Note that FormBuilder provides these as strings, so they must be parsed using JSON.parse() before being passed to the RJSF Form.

import React, { useState } from 'react';
import { FormBuilder } from '@ginkgo-bioworks/react-json-schema-form-builder';
import { withTheme } from '@rjsf/core';
import { Theme as MuiTheme } from '@rjsf/mui';
import validator from '@rjsf/validator-ajv8';

const Form = withTheme(MuiTheme);

function Example() {
  const [schema, setSchema] = useState('{}');
  const [uischema, setUiSchema] = useState('{}');
  const [formData, setFormData] = useState({});

  return (
    <div>
      <FormBuilder
        schema={schema}
        uischema={uischema}
        onChange={(schema, uischema) => {
          setSchema(schema);
          setUiSchema(uischema);
        }}
      />
      <Form
        schema={JSON.parse(schema)}
        uiSchema={JSON.parse(uischema)}
        onChange={(data) => setFormData(data.formData)}
        formData={formData}
        validator={validator}
      />
    </div>
  );
}

export default Example;

You can customize the behavior and appearance of the 'Add' buttons (the + buttons) in several ways:

1. Change Labels

Update the text used for adding elements or sections via the labels object in mods.

2. Programmatic Addition

You can trigger the addition of elements or sections from anywhere in your application using addCardObj or addSectionObj. These functions require an object of type AddFormObjectParameters.

To get the necessary categoryHash required by these functions, use the onMount callback on the FormBuilder component to capture the InitParameters.

3. Override the Add Component

To completely replace the UI of the 'Add' buttons, provide a callback function to mods.components.add. This callback receives AddFormObjectParameters and should return a React component.

import { 
  FormBuilder, 
  addCardObj, 
  addSectionObj, 
  type AddFormObjectParameters, 
  type InitParameters 
} from '@ginkgo-bioworks/react-json-schema-form-builder';
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';

function MyFormBuilder() {
  const [categoryHash, setCategoryHash] = useState('');

  const mods = {
    components: {
      add: (addProps: AddFormObjectParameters) => (
        <Stack direction="row" spacing={1}>
          <Button onClick={() => addCardObj(addProps)}>Add Element</Button>
          <Button onClick={() => addSectionObj(addProps)}>Add Section</Button>
        </Stack>
      ),
    },
  };

  return (
    <FormBuilder
      onMount={(params: InitParameters) => setCategoryHash(params.categoryHash || '')}
      mods={mods}
      // ... other props
    />
  );
}