Model Properties

Options available within a single content model definition in Stackbit.

The models property is how content models are specified in Stackbit. This document details the properties available within a model definition.

Usage

Each model is defined as a property within the models property on the primary Stackbit configuration object. The name of the property indicates the name of the model (or ID, in some CMSs), while the value is the model definition.

In the example below, we're showing a configuration that defines two models — Page and Post. Within each of these objects can be the options shown below.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
export default {
  models: {
    Page: {
      // page properties ...
    },
    Post: {
      // post properties ...
    },
  },
  // other properties ...
}

See the name property for model naming limitations.

Legacy YAML Configuration

YAML Config Deprecated

Using the legacy YAML configuration is deprecated and may be removed in a future version of Stackbit. Please consider updating to JavaScript configuration.

If using the legacy YAML configuration, note that you do not need to use the models property, but can instead place individual model definitions in the .stackbit/models directory.

Model Definition Options

The following properties are available when configuring a model definition.

description

Description of the model.

Required
No
Allowed Values
String
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
export default {
  models: {
    SiteSettings: {
      description: 'Global settings used throughout the site.',
    },
  },
}

extends

Models that are extended from other models inherit all fields in the models included in the list. This model can then define any new fields of its own.

Required
No
Allowed Values
Array of one or more model names, as strings.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
export default {
  models: {
    HeroSection: {
      extends: ['Section'],
    },
    Section: {
      // model definition ...
    },
  },
}
  • If this model declares a field with the same name as a field it inherited, then that field's attributes are merged: any field attributes explicitly set in this model are used. Then, inherited field attributes are used as long as they as not overridden in the model.
    • That means you can not only override field attributes fully, but also easily add/change specific attributes of inherited fields, e.g. setting a default for a field which better matches this model.

fieldGroups

This attribute is used by the editor UI to visually place related fields in separate groups. This has no effect on the content itself or how it is stored - it is only used to make editing content pieces with multiple fields easier.

This attribute works in tandem with the group attribute for fields.

Required
No
Allowed Values

List of objects with the following properties:

name (required): String representing the name of the group.

label (required): Display label for the tab.

icon: Name of icon. The list can be found in our component playground.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
export default {
  models: {
    HeroSection: {
      fieldGroups: [
        { name: 'styles', label: 'Styles', icon: 'palette' },
        { name: 'settings', label: 'Settings', icon: 'gear' },
      ],
      fields: [{ type: 'enum', name: 'colors', group: 'styles' }],
    },
  },
}
  • Any field that does not has an assigned group is put by the editor UI under the default group "Content" (regardless of whether any field groups were defined).
  • Available icon values are listed until the icon control in our component playground.

    Field groups icon component control
    Field groups icon component control

fields

The definition for specifying or overriding fields on a model.

Required
Yes, unless simply overriding model properties from an API CMS.
Allowed Values
An array of objects, with properties found in the fields reference.
Default
A human-friendly name, based on the name property.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
export default {
  models: {
    Page: {
      fields: [
        // field definitions go here ...
      ],
    },
  },
}

filePath

This property only applies to Git CMS.

The path at which to store new page and data content created by editors using Stackbit's application. Stackbit stores new pages at {pagesDir}/{filePath} and non-pages under {dataDir}/{filePath}.

Required
If type is page or data.
Allowed Values

Path to find and store new content files, with supported interpolation.

Allowed Extensions
.json, .md, .toml, .yaml, .yml
Interpolated Variables

title: The title, manually set by the editor.

slug: The slug field, manually set by the editor.

moment_format: A formatted version of today's date using Moment.js formats. Note: Use date as the first argument with this option.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
export default {
  dataDir: 'content/data',
  models: {
    SiteSettings: {
      type: 'data',
      filePath: 'site-settings.json',
    },
  },
}
  • Single-instance models should point to a specific file, while models with multiple content objects should use variable interpolation to create dynamically-named pages.
  • Variables can be interpolated using curly brackets. Examples:
    • filePath: '{slug}.md'
    • filePath: 'posts/{moment_format(date, 'YYYY-MM-DD')}-{slug}.yaml'
  • The UI has special handling for index pages:
    • When a user adds a new page and sets its path it /plans/ (note the trailing slash!), the page content will be stored to the file /content/pages/plans/index.md
    • When you navigate to this page, the UI will know to map the URL /plans/ back to /content/pages/plans/index.md.

groups

Adds the model to a specific group for use with the groups field attribute.

Required
No
Allowed Values
Array of strings
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
export default {
  models: {
    CaseStudySection: {
      groups: ['SectionComponent'],
    },
    Page: {
      field: [
        {
          name: 'sections',
          type: 'list',
          items: [{ type: 'model', groups: ['SectionComponent'] }],
        },
      ],
    },
  },
}
  • When defining fields of type model or reference which point to other model names, you may wish to have a list of acceptable model names which is not hard-coded, e.g. "any section-like component is applicable for nesting here", or "any person-like component can be referenced from here".
  • In the example above, the CaseStudySection model declares that it belongs in the SectionComponent group. Here is how this group name is then used for the sections field in the Page model.

hideContent

This property only applies to Git CMS.

By default, the UI assumes that any page models implicitly have a content field with Markdown-formatted content. When the page is edited in the UI, this field will be available to edit under a field labeled Content.

Required
No
Allowed Values
true, false
Default
false
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
export default {
  models: {
    Page: {
      hideContent: true,
    },
  },
}
  • For this functionality to work, defined page model files must have an .md extension.
  • For pages whose model declared hideContent: true, you will find only front matter in files.
  • Content for a page where hideContent is false is available in a property named markdown_content.

label

A short, descriptive name for the model that is shown to the content editor in various elements of our UI.

Required
No
Allowed Values
String
Default
A human-friendly name, based on the name property.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
export default {
  models: {
    CaseStudySection: {
      label: 'Case Study',
    },
  },
}
  • Because this is only for display purposes, you can freely change it without breaking any other models or content.

labelField

Used by the visual editor to make it easier to navigate between and within pages. Whenever a content item name is shown in the editor, the value of the field in that content item will be used to label the item.

Required
No
Allowed Values
The name of an existing field in the same model, whose value best describes the specific content item.
Default

Stackbit tries to find the most relevant field to use as the label by looking for fields on the model in this order:

  1. title
  2. label
  3. The first defined field of type string with content
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
export default {
  models: {
    CaseStudySection: {
      labelField: 'heading',
      fields: [
        {
          name: 'heading',
          // ...
        },
      ],
    },
  },
}

name

The unique name of the model, which is often the ID for API CMSs. This is not a title or label, which are typically used only for display purposes.

Required
Not if models property if defined as an object, in which case the name of the model is the property's name.
Allowed Values

A string following these rules:

  • Must start and end with a letter
  • Can contain only lower case alphanumeric characters or underscores (_)
Default
The name of the property defined in the models object.
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
export default {
  models: {
    CaseStudySection: {
      // This is unnecessary because the property name (key) has already defined
      // the name.
      name: 'CaseStudySection',
    },
  },
}
  • The model's name is used whenever an instance of this model is stored or this model is referenced anywhere, and thus it typically should not be changed. When you have control over the name of the model, we suggest using PascalCase (e.g. CaseStudySection).
  • If using Git CMS, the model name is included in all content items via their type attribute, which is automatically set by Stackbit when the content is stored. In other words, the model name is the content type.

type

The type of the model. Learn more about model types.

Required
Only if value is data.
Allowed Values

page: Highest-level content specific to a URL path on your site.

object: Repeatable content that is embedded in another model (of any type).

data: Content objects which are meant either to stand alone and be accessed globally, or to be referenced from a page.

Default
Inferred based on context (i.e. other properties within the model).
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
export default {
  models: {
    site_settings: {
      type: 'data',
    },
  },
}
  • page and data must also specify the filePath property.
  • page must specify the urlPath property.

urlPath

The urlPath setting tells Stackbit how to build the sitemap by providing a path for all of a model's page.

Required
No
Allowed Values
URL-friendly characters, with interpolation (see below)
Default
/{slug}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
export default {
  models: {
    post: {
      type: 'page',
      urlPath: '/blog/{slug}',
    },
  },
}
  • Values inside curly braces are interpolated to resolve individual page properties. For example, if the urlPath were set to /blog/{id}, Stackbit will retrieve all documents of the model and use each one's id property to build an array of paths for the sitemap — e.g. ["/blog/1", "/blog/2", "..."].
  • For singleton models (models with only a single document), the urlPath can be hard-coded to explicitly what the path should be. Example for a model that holds a single blog feed page:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    export default {
      models: {
        BlogPage: {
          type: 'page',
          urlPath: '/blog',
        },
      },
    }