Presets are sets of initial field values for new content objects created in the UI. Learn more about why and when to use presets in the conceptual guide.

Preset Files

Presets are always in your project repository. They are read from JSON files under .stackbit/presets. Each file defines one or more presets for one specific model.

└── .stackbit
    ├── models
    └── presets
        ├── author.json
        ├── button.json
        ├── hero_section.json
        ├── post.json
        └── ...

It is recommended, though not mandatory, to name the files by the model name. The actual model name is defined in the model property within the file.

Example

Here are example contents for a preset file. It contains two presets for the PageLayout model.

{
  "model": "PageLayout",
  "presets": [
    {
      "label": "Contact",
      "thumbnail": "images/page-contact.png",
      "data": {
        "title": "Contact us",
        "sections": [
          {
            "type": "HeroSection",
            "title": "Contact us",
            "feature": {
              "type": "FormBlock",
              "action": "/.netlify/functions/submission_created",
              "fields": [
                {
                  "type": "EmailFormControl",
                  "label": "Email"
                }
              ]
            },
            "styles": {
              "self": {
                "alignItems": "center",
              },
              "title": {
                "fontWeight": 700
              }
            }
          }
        ]
      }
    },
    {
      "label": "About",
      "thumbnail": "images/page-about.png",
      "data": {
        "title": "About us",
        "sections": [
          ...
        ]
      }
    }
  ]
}

File Format

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.

model

This is the name of the model. It is often helpful to have the filename related to the model name for easier navigation among your preset files.

presets

Each entry in the presets is a single preset. The entry has the following properties:

  • label: The preset name displayed in the UI.
  • thumbnail: 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.
  • data: Holds the field values to set. You don't need to include all fields in the model, only the ones this preset should set. As you can see in the example above, initial values can be full sub-objects having multiple levels of nesting. It is also common to set the styles field so that you get not only pure content but also the appropriate design.

The data object is in the same format as stored content files, i.e. actual pages. Thus, to build a complex preset it is often convenient to copy the content of an actual page into your preset file. See below for an example.

Values in presets vs. default field 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.