If you aren't familiar with presets, we recommend you read the conceptual 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 presetSources in stackbit.yaml.

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.

{
  "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.

Page vs Component 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.

presets

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

  • label: string - The preset name displayed in the UI.
  • thumbnail: 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.
  • metadata: 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: object - Field values which should be set by the chosen preset. You may also include nested objects and styles properties.
{
  "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": [
          {
            "heading": "How Stackbit Works →",
            "subheading": "Follow an end-to-end guide to learn the inner-workings of Stackbit.\n",
            "url": "https://docs.stackbit.com/conceptual-guides/how-stackbit-works/",
            "$$type": "Card"
          },
          {
            // additional cards ...
          }
        ]
      }
    },
    {
      // additional card grid presets ...
    }
  ]
}

See below for further nuance within the properties above.

It may also be helpful to refer to step-by-step guides on presets:

Mapping Properties to UI Controls

Preset UI Mapping

Here is how these properties affect what you see in the UI:

  1. label
  2. thumbnail (as an image src path)
  3. Meant to designate that an editor created the preset, triggered by the presence of metadata.categories.
  4. metadata.canDelete is set to true, also referring to an editor-generated preset.
  5. A listing of values in metadata.categories for all relevant presets within the current context.

Including Thumbnail Previews

Thumbnails provide a means for content editors to preview what they are going to be adding to the page before the content is created.

We recommend placing thumbnail previews in a .stackbit/presets/images directory. (This is where Stackbit puts auto-generated previews for presets created by editors.) The thumbnail path is relative, and therefore should begin with images if using this directory.

{
  "model": "CardGridSection",
  "presets": [
    {
      "thumbnail": "images/card-grid-section-basic-card-grid.png"
      // ...
    }
  ]
}

Embedding Nested Objects

The data object is a representation of the content that should be added when the preset is chosen. The data can be nested as deeply as is required to provide the appropriate content. In the example below, a card grid preset is bringing data for the cards within the grid.

{
  "model": "CardGridSection",
  "presets": [
    {
      "data": {
        "cards": [
          // nested card data
          {
            "heading": "How Stackbit Works →",
            "subheading": "Follow an end-to-end guide to learn the inner-workings of Stackbit.\n",
            "url": "https://docs.stackbit.com/conceptual-guides/how-stackbit-works/",
            "$$type": "Card"
          }
        ]
      }
    }
  ]
}

Setting Styles

Because you can include any relevant content in the data property and because some styles can be driven by content, you can also include user-controlled style values here, too.

Consider if a card being used here had a textAlign style option.

{
  "model": "CardGridSection",
  "presets": [
    {
      "data": {
        "cards": [
          // nested card data
          {
            "heading": "How Stackbit Works →",
            "subheading": "Follow an end-to-end guide to learn the inner-workings of Stackbit.\n",
            "url": "https://docs.stackbit.com/conceptual-guides/how-stackbit-works/",
            // Can also include user-controlled style values.
            "styles": {
              "self": {
                "textAlign": "center"
              }
            },
            "$$type": "Card"
          }
        ]
      }
    }
  ]
}

Preset Data vs Default Values

If a content preset is selected by the user, and that preset includes a value for a field having a default in the model file, then the value in the preset takes precedence.

Do note that presets do not affect any fields they do not explicitly set. Meaning, any fields not included in the preset will have their default value left intact.

Markdown Body Content

When using file-based content (Git CMS), the content in the body of a file is stored in a special property called markdown_content. This is often used in page models where the layout is fixed — a blog post is a common example.

You can set this property directly in the preset to control the default body of the page object.

{
  "model": "Post",
  "presets": [
    {
      "data": {
        "markdown_content": "Body content for the post created from this preset ..."
        // ...
      }
    }
  ]
}

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.