Presets API

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.

{
  "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 Netlify Create-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 Netlify Create Works →",
            "subheading": "Follow an end-to-end guide to learn the inner-workings of Netlify Create.\n",
            "url": "/create/concepts/how-create-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:

Netlify Create 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 Netlify Create 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 Netlify Create 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 Netlify Create 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.

File-Based Presets API#

model#

presets#