Field Properties

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

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#

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.

default#

Stackbit 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' }],
    },
  },
}