Presets

Configuration API reference for page and component presets.

If you aren't familiar with presets, we recommend you read the feature guide before diving into the presets API.

Preset Configuration Location

The default location for preset configuration files is .stackbit/presets in your site's repository. This can be customized using the presetSources config property.

Presets API

Each file in the presets directory must contain two keys:

model
Name of the model for which the presets are being defined.
presets
An array of preset objects.

See below for more information.

model

Each preset file may contain one and only one model property representing the name of the model to which its presets apply.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
{
  "model": "Card",
  "presets": [
    // preset config ...
  ]
}

It is helpful to relate the preset filename to the model property. This makes for easier navigation among preset files.

presets

Presets are supported for any component that is modeled and used within your site. This includes both pages, as well as components nested to any depth within the page.

Each entry in the presets contains the configuration for a single preset. The entry has the following properties:

label
Required string. The preset name displayed in the UI.
thumbnail
Required string. An optional path to an image file to display in the UI as a thumbnail. The path should be relative to the preset files directory. We recommend placing thumbnail previews in a .stackbit/presets/images directory.
metadata

Required object. Sets controls for what editors can and can't do with presets. Includes the following properties:

  • categories: string[] An array of category names used to group this preset in the application.
  • canDelete: boolean Controls if content editors can delete the preset. If this is not set, a preset can only be deleted by removing the code — not through the application.
data

Field values which should be set by the chosen preset. You may also include nested objects and styles properties.

See the data attributes section below for information on Stackbit-specific properties.

styles
This is nested in the the data property as an object. you can include user-controlled style values here because some styles can be driven by content.
markdown_content
This is nested in data property as an object. When using file-based content (Git CMS), the content in the body of a file is stored in this propery. It is often used in page models where the layout is fixed — a blog post is a common example
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
{
  "model": "CardGridSection",
  "presets": [
    {
      "label": "Basic Card Grid",
      "thumbnail": "images/card-grid-section-basic-card-grid.png",
      "metadata": {
        "categories": ["Grids"],
        "canDelete": true // Users can delete this preset.
      },
      "data": {
        "heading": "Jump to Topic",
        "subheading": "Or jump right to a specific topic to help you build your site.\n",
        "cards": [
          {
            "$$type": "Card",
            "heading": "How Stackbit Works →",
            "subheading": "Follow an end-to-end guide to learn the inner-workings of Stackbit.\n",
            "url": "https://docs.stackbit.com/concepts/how-stackbit-works/",
            // Can also include user-controlled style values.
            "styles": {
              "self": {
                "textAlign": "center"
              }
            }
          },
          {
            // additional cards ...
          }
        ]
      }
    },
    {
      // additional card grid presets ...
    }
  ]
}

See below for further nuance within the properties above.

It may also be helpful to refer to the feature guide.

Preset Data Attributes

The object contained within the data property of a particular preset is the data that gets stored in the content source when a component is added using the preset. The properties in this section are reserved and result in specific behavior when creating content from the preset.

$$ref

When the field within an object is of type reference and the preset is configured to refer to an existing document, the $$ref property provides Stackbit with the ID value of the existing document in the content source.

This also applies to remote assets, where the value of $$ref should be the ID of the image in the content source. (This does not apply to assets stored in the repository, where value is the relative local path to the image file.)

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
{
  "model": "page",
  "presets": [
    {
      "label": "Landing Page",
      "thumbnail": "images/landing-demo.png",
      "data": {
        "section": {
          "$$ref": "id_of_a_section"
        },
        "image": {
          "$$ref": "id_of_an_image"
        }
      }
    }
  ]
}

If your preset is configured to create a reference from static properties and not an existing document, use the $$type property instead.

$$type

When the field within an object is of type reference or model, and the preset is configured to create a new object in the content source, the $$type property provides Stackbit with the ID value of the appropriate model to use when creating the new, referenced document.

This property should be used even when the field can be of only a single model.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
{
  "model": "page",
  "presets": [
    {
      "label": "Landing Page",
      "thumbnail": "images/landing-demo.png",
      "data": {
        "section": {
          // If section is of type `model` or `reference` specify the
          // model name of the object to create, ...
          "$$type": "HeroSection",
          // ... then specify the rest of the fields to populate in
          // the new object or document.
          "title": "New Hero Section"
        }
      }
    }
  ]
}

Note that $$type does not need to be used when $$ref is set, as Stackbit will be able to infer the type from the referenced document.

Handling References in API Sources

For API CMSs, there are scenarios in which you may or may not want to duplicate references when creating content from presets. These options are defined in the project configuration.

Note that changes you make to the global configuration of presets only applies to new presets, given that presets are stored as files.