Fields are added to forms via the fields array and create the editing interface of a form.

Field Config

All field plugins share a common config:

interface FieldConfig {
  name: string
  component: string | ReactComponent
  label?: string
  parse?(value: any, name: string, field: Field): any
  format?(value: any, name: string, field: Field): any
  validate?(
    value: any,
    allValues: any,
    meta: any,
    field: Field
  ): string | object | undefined
}
keydescription
nameEquivalent of an input's name attribute.
componentEither a string denoting a field already registered with the CMS, or a custom field component.
labelOptional: A label to render above the field input.
parseOptional: Prepare the data for usage in the field component.
formatOptional: Prepare the data for saving.
validateOptional: Return undefined when valid. Return a string or an object when there are errors.

Default Field Plugins

These are the default field plugins available through the CMS:

External Field Plugins

These are plugins that must be installed through separate packages:

Field Definition

You can add fields to a form through the fields array in the form configuration. The Field definition at minimum needs a name and component. This is an example of a simple text field definition.

Example form configuration

const formOptions = {
  id: 'lynel-hoofs',
  label: 'Edit This Page',
  fields: [
    {
      name: 'tagline',
      component: 'text',
    },
  ],
}

Refer to individual field plugin docs for additional examples.

name

The name property connects the field with the source data by providing the path to that content from the root of the source data.

For example, say we had a JSON object:

{
  "headline": "Banana Pancakes"
}

Our field definition to edit headline would be:

{
  fields: [
    {
      name: 'headline',
      component: 'text',
    },
  ],
}

If the data structure looked a little different:

{
  "hero": {
    "headline": "Banana Pancakes"
  }
}

The name property should be updated to reflect the different path:

{
  fields: [
    {
      name: 'hero.headline',
      component: 'text',
    },
  ],
}

Check out the final-form docs for a more detailed look at how the name field works.

component

The component field property can either be the name of a field plugin (a string), or a React Component.

All of the previous examples show the component being set with a string:

{
  fields: [
    {
      name: 'background_color',
      component: 'color',
    },
  ],
}

'color' is referring to the name of the Color Field Plugin that is hooked up to the CMS by default.

You can also define components to render in place of a default field:

Example

const formOptions = {
  label: 'My Page',
  fields: [
    {
      label: "Athlete's Name",
      name: 'name',
      component: 'text',
    },
    // The custom inline field
    {
      name: '_',
      component: () => <h4>Best Scores</h4>,
    },
    {
      name: 'scores',
      component: 'list',
      field: 'number',
    },
  ],
}

In the example above, the custom field component isn't being used to edit data, but rather as a method of customizing the sidebar organization.

Additional Reading

Last Edited: August 5, 2020