Model Properties

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.

export default {
  models: {
    Page: {
      // page properties ...
    },
    Post: {
      // post properties ...
    },
  },
  // other properties ...
}

See the name property for model naming limitations.

Legacy YAML 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.

actions#

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

• type is inferred and not required
• model and document are available within the state and run options parameter, referring to the document and model on which the action is performed.
• 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

description#

Description of the model.

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.

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.

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.

  

fields#

The definition for specifying or overriding fields on a model.

export default {
  models: {
    Page: {
      fields: [
        // field definitions go here ...
      ],
    },
  },
}

filePath#

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

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.

export default {
  models: {
    CaseStudySection: {
      groups: ['SectionComponent'],
    },
    Page: {
      field: [
        {
          name: 'sections',
          type: 'list',
          items: [{ type: 'model', groups: ['SectionComponent'], models: [] }],
        },
      ],
    },
  },
}

• 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#

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.

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.

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.

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.

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.

readOnly#

Prevents documents of this model from being created or deleted.

This is useful for global, singleton models, which are typically used to affect globally-shared content on the site, such as settings, styles, and default SEO values.

export default {
  models: {
    site_settings: {
      readOnly: true,
    },
  },
}

• This does not prevent a document's fields from being edited. Read-only fields must be defined at the field level.

type#

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

export default {
  models: {
    site_settings: {
      type: 'data',
    },
  },
}

• page and data must also specify the filePath property.
• page must specify the urlPath property.
• Setting page will enable the ability to create new pages in the visual editor. To ensure this works properly, you must do both of the following:
  • Either Define urlPath on the model OR return the page as the document object in the siteMap property.
  • Have a valid front-end page at the resolved urlPath. When a new page is created, Stackbit automatically redirects to the new page using 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.

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