Presets API

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.

Presets are stored in JSON files in the project's repository by default, but can also be stored in a remote content source with the appropriate configuration. See here for more information about remote presets.

The structure of file-based presets objects and remote presets is different. Both are referenced below.

File-Based Presets API

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

Each file in the presets directory must contain two keys, as noted below:

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.

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

Remote Presets Fields

When using a content source defined with the contentSources property, presets can be stored in a remote content source by creating a stackbitPreset model with the fields shown in the table below.

label
string
thumbnail
media or image, depending on the content source's capabilities and configuration options
data
json or text, depending on the content source's capabilities and configuration options

Note the following:

  • Stackbit will use the first stackbitPreset model it finds from sources defined in contentSources, starting from the first element in the array.
  • File-based presets can not also be used and the presetSource property will be ignored.
  • The data stored in the data field includes additional information beyond what you would find in a file-based preset. For example, metadata is embedded in data in a remote preset, while it is a sibling to data in a file-based preset.

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
The ID of an existing document, used when the preset includes a reference to an existing document.
$$type
The ID of a model, used when the preset creates a new reference or nested object that uses another model to define its shape.

See the sections below for more information about these properties.

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

Below is an example using file-based presets. Presets stored remotely follow the same concept, but the structure of data differs slightly.

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

Below is an example using file-based presets. Presets stored remotely follow the same concept, but the structure of data differs slightly.

  • 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

When the presets refer to content stored in API-based content sources, 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.