Field Properties

Attributes for fields belonging to a model in Netlify Create configuration.

Fields are how you can specify or override the appearance of a field in the Netlify Create editor, 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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
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.

Required
No
Allowed Values
A constant value that should be used when the creating a new content piece.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
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.

Required
When controlType is set to custom-inline-html or custom-modal-html.
Allowed Values
Path to a local file that contains the HTML for the field's control, relative to the project root. See control types for more information on shared control types.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
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.

Required
No
Allowed Values

All field types have access to the following control types:

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

Some field types support additional control types, which are documented on their respective pages:

See below for more information on shared control types.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
export default {
  models: {
    Page: {
      fields: [
        {
          type: 'string',
          name: 'emoji',
          controlType: 'custom-inline-html',
          controlFilePath: '.stackbit/fields/emoji.html',
        },
      ],
    },
  },
}

default

Netlify Create sets this value to the field when adding a new page or adding a component to a page.

Required
No
Allowed Values
The initial value for this field when creating new content.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
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.

Required
No
Allowed Values
A string with the appropriate text.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
export default {
  models: {
    Page: {
      fields: [
        {
          name: 'heading',
          type: 'string',
          description: 'Help or descriptive text for this field ...',
        },
      ],
    },
  },
}
Field Description Tooltip
Field Description Tooltip

group

Places the field within the appropriate tab.

Required
No
Allowed Values
name from fieldGroups definition representing the tab in which the field should be visible.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
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.

Required
No
Allowed Values
true, false
Default
false
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
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.

Required
No
Allowed Values
String
Default
A human-friendly string, inferred from the name attribute.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
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.

Required
Yes
Allowed Values

String following these rules:

  • Contain only alphanumeric characters, underscores or hyphens.
  • Start with a letter.
  • Cannot end with an underscore or a hyphen.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
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.

Required
No
Allowed Values
true, false
Default
false
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
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.

Required
No
Allowed Values
true, false
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
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.

Required
Yes
Allowed Values

A valid field type as a string. Choosing a field type can lead to additional required fields and variations on default values, which are documented in individual pages, linked below.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
export default {
  models: {
    Page: {
      fields: [{ name: 'title', type: 'string' }],
    },
  },
}

Control Types

The following control types are available for all field types:

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).

controlType
custom-inline-html
controlFilePath
Path to the HTML to render within the iframe, relative to the project root.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
export default {
  models: {
    Page: {
      fields: [
        {
          type: 'string',
          name: 'emoji',
          controlType: 'custom-inline-html',
          controlFilePath: '.stackbit/fields/emoji.html',
        },
      ],
    },
  },
}
Custom Inline HTML Control
Custom Inline HTML Control
  • The HTML file must implement a global window.stackbit object containing an onUpdate function for hooking into the Netlify Create 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.

Custom Modal Control - Open Button
Custom Modal Control - Open Button

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

Custom Modal Control - Modal Window
Custom Modal Control - Modal Window