Field Properties

Fields are how you can specify or override the appearance of a field in the visual editor UI, along with other behavior attributes.

Usage#

All fields declared by a model are listed as objects under in the fields property (as an array of objects).

In this example, we're showing a simple Page model with a single title field.

export default {
  models: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        // other field definitions ...
      ],
      // other model properties ...
    },
  },
  // other properties ...
}

Extending Fields#

Note that when models are extended from other models, you are only required to set the field properties that you'd like to override. A property listed as required below will not be needed if it was set on an extended field.

Field Attributes#

actions#

Model actions match global and bulk custom actions, except for the following differences:

• type is inferred and not required
• The following properties are available within the state and run options parameter:
  • parentDocument: Document in which the current field exists.
  • parentModel: Model in which the current field was defined.
  • documentField (optional): Field object for the action's field.
  • modelField: Field definition for the action's field.
  • fieldPath: Path to the field within the document object, using dot notation for nested content.
• contentSourceActions is also available to the run function. This is an object that includes the following functions that get passed onto the content source module:
  • createDocument
  • updateDocument
  • deleteDocument
  • publishDocuments

const#

Allows a constant value to be set for a field. The UI will display that value as read-only and will not let the user change it.

export default {
  models: {
    Page: {
      fields: [{ name: 'layout', type: 'string', const: 'Page' }],
    },
  },
}

• You can achieve the same effect by setting readOnly to true and defining a value for default.
• When using const, do not define default — it will have no effect.
• If you don't want the field to be visible in the UI, also set hidden: true for that field.

controlFilePath#

Provides a reference to a file that determines how a field is rendered when required by control type.

export default {
  models: {
    Page: {
      fields: [
        {
          type: 'string',
          name: 'emoji',
          controlType: 'custom-inline-html',
          controlFilePath: '.stackbit/fields/emoji.html',
        },
      ],
    },
  },
}

• The path is relative to the project root directory. Leading with a slash (/) or dot (.) has no additional effect — the path will still be relative to the project root.

controlType#

Determines how the field is rendered in the page and content editors.

export default {
  models: {
    Page: {
      fields: [
        {
          type: 'string',
          name: 'emoji',
          controlType: 'custom-inline-html',
          controlFilePath: '.stackbit/fields/emoji.html',
        },
      ],
    },
  },
}

default#

The visual editor sets this value to the field when adding a new page or adding a component to a page.

export default {
  models: {
    Page: {
      fields: [{ name: 'title', type: 'string', default: 'My New Page' }],
    },
  },
}

• This is not a fallback value. if a field's value is empty when publishing the content, its value is not set back to default.

description#

Descriptive or help text, presented as a tooltip when hovering over the info icon.

export default {
  models: {
    Page: {
      fields: [
        {
          name: 'heading',
          type: 'string',
          description: 'Help or descriptive text for this field ...',
        },
      ],
    },
  },
}

group#

Places the field within the appropriate tab.

import { defineStackbitConfig } from '@stackbit/types'

export default defineStackbitConfig({
  stackbitVersion: '~0.6.0',
  modelExtensions: [
    {
      name: 'hero',
      fieldGroups: [{ name: 'styles', label: 'Styles', icon: 'palette' }],
      fields: [{ name: 'bgColor', group: 'styles' }],
    },
  ],
})

hidden#

If you're setting a fixed constant value for a field (see the const property) and you don't want that field to be at all visible to content creators in the visual editor, you can hide it with this property.

export default {
  models: {
    Page: {
      fields: [{ name: 'layout', type: 'string', const: 'Page', hidden: true }],
    },
  },
}

label#

This property denotes an optional human-friendly name that will be used in the UI. It can be changed without affecting stored data or other models.

export default {
  models: {
    Page: {
      fields: [{ name: 'title', type: 'string', label: 'Heading' }],
    },
  },
}

name#

The name of the field is the key used to store it in the content source.

export default {
  models: {
    Page: {
      fields: [{ name: 'title', type: 'string' }],
    },
  },
}

readOnly#

Limits editing on the field, depending on the field's type. See below for more information.

export default {
  models: {
    Page: {
      fields: [
        { name: 'title', type: 'string', required: true },
        { name: 'lastUpdated', type: 'date', readOnly: true },
      ],
    },
  },
}

• For flat or primitive field types (string, number, boolean, etc.), setting readOnly to true prevents the field from being edited.
• For most nested or more complex fields (reference, model, cross-reference, object, list), setting to true prevents editors from adding or removing the object or reference. It does not prevent editing fields within the nested/referenced object/document. readOnly must be set on every field that should not be editable.
• list fields also cannot be reordered if readOnly is true, in addition to the behavior mentioned above.

required#

If a field is required and left empty in a piece of content, publishing will result in an error message to the content editor.

export default {
  models: {
    Page: {
      fields: [{ name: 'title', type: 'string', required: true }],
    },
  },
}

type#

Specifies the type of field, which affects other available attributes and default values. Each type has its own documentation page, which is listed below.

export default {
  models: {
    Page: {
      fields: [{ name: 'title', type: 'string' }],
    },
  },
}

Control Types#

The following control types are available for all field types:

• custom-inline-html
• custom-modal-html
• custom-inline-script
• custom-modal-script

See below for usage information. Or see the custom fields guide for more information on working with custom fields.

custom-inline-html#

Renders an HTML page within an iframe element.

When using this control type, the following properties must be defined (in addition to required field properties).

export default {
  models: {
    Page: {
      fields: [
        {
          type: 'string',
          name: 'emoji',
          controlType: 'custom-inline-html',
          controlFilePath: '.stackbit/fields/emoji.html',
        },
      ],
    },
  },
}

• The HTML file must implement a global window.stackbit object containing an onUpdate function for hooking into the visual editor. See the control hooks client API reference for usage details.

custom-modal-html#

Works identically to custom-inline-html, but displays the HTML in a modal window instead of an iframe.

The field control is an Open button that triggers the modal.

Clicking the Open button opens the modal, which displays the HTML in an iframe within the modal.

custom-inline-script#

Renders an HTML page within an iframe element.

When using this control type, the following properties must be defined (in addition to required field properties).

export default {
  models: {
    Page: {
      fields: [
        {
          type: 'string',
          name: 'emoji',
          controlType: 'custom-inline-script',
          controlFilePath: '.stackbit/fields/emoji.js',
        },
      ],
    },
  },
}

• Component should render itself either into a div with id root or directly into document.body.
• Component must implement a global window.stackbit object containing an onUpdate function for hooking into the visual editor. See the control hooks client API reference for usage details.
• React and ReactDOM is available in the iframe environment via window.React and window.ReactDOM. In case custom control uses React for render, it can exclude it's source code from the bundle and use the provided, which will reduce the load time of the custom control.

module.exports = {
  entry: './index.tsx',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'index.js'
  },
  
  externals: {
    react: 'React',
    'react-dom': 'ReactDOM'
  },
  externalsType: 'global'
};

custom-modal-script#

Works identically to custom-inline-script, but displays the HTML in a modal window instead of an iframe.