Content Presets

Define content variations that editors can use to quickly create new pages and components.

Presets are predetermined variations of content that can be used to provide content editors with a quick way to create new, visually-rich pages and components.

With Stackbit, both pages and components are represented by content models, and presets must be defined against a specific model.

Component Presets View
Component Presets View

How Presets Work

Preset definitions are read by Stackbit, and the results displayed when a content editor chooses to create a page or new component. When the page is created or the component added to a page, Stackbit adds the new content to the site based on the preset's configuration.

An example of adding a new component from a preset can be seen in the image above.

By default, presets are stored in files in the .stackbit/presets directory within your repository. However, presets can be stored in a remote content source if configured correctly. See below for more information on both of these scenarios.

File-Based Presets

By default, Stackbit looks for presets defined in the .stackbit/presets directory. This can be customized using the presetSource option.

Preset files each define one or more presets for one particular content model used in your site. Learn more about the preset configuration API.

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

API-Based Presets

Stackbit will store presets in a remote content source under the following conditions:

  • The contentSources property is used to define the content source.
  • A defined content source includes a stackbitPreset model, with the following fields:
    • label (string)
    • thumbnail (media/image)
    • data (json/text)

If adding this model after while working in a cloud project, the container must be restarted for the remote preset source to be picked up.

Using this feature has the following side-effects and conditions:

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

Creating Presets

The easiest way to create presets is to use the Save as Preset feature, available to content editors.

Creating a new preset using the Save as Preset feature does the following:

  1. Stores the preset's content in the appropriate location.
  2. Generates a thumbnail preview of the component, and places the file in the appropriate source. (For file-based presets, this is in the .stackbit/presets/images directory.)

Building Presets from Scratch

Because presets are stored as JSON files or records in your content source, you can also build presets from scratch.

If doing so, we recommend working locally and using the preset configuration API reference to see the available options.

Pro Tip

Be sure to add a thumbnail images to your presets when creating manually so your editors know how the new component is going to appear on the page.

Sharing Presets Across Projects

This applies to file-based presets only. Presets stored in a remote content source are automatically shared among projects using that source.

The presetSource property makes it possible to load presets from the node_modules directory in your project. This unlocks the ability to share presets across multiple projects.

To add shared presets to your project:

  1. Publish your shared presets to NPM (or similar registry)
  2. Add the package as a dependency in your project
  3. Use the presetSource option to add the proper path to the directory in the package containing the presets
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
export default {
  presetSource: {
    type: 'files',
    presetDirs: ['node_modules/some-package/.stackbit/presets', 'my-presets'],
  },
  // other properties ...
}

Developing Shared Presets

When building shared presets, you want to make sure they are going to be available to your shared projects before publishing. To do so, we recommend working locally with an example project that links to some other local directory (or Git submodule) to ensure the presets are configured properly.

Handling Nested Objects

Stackbit page models can include fields which embed object models inside the page. Object models can also recursively include fields that embed structured content representing another object model.

In other words, as components are represented by object models in Stackbit, components can have subcomponents which are also represented by an object model.

While presets are defined at the model level, they can also include any necessary embedded content (i.e. children). For example, a CardGrid preset can also include embedded content for an array of Card components. Using this preset would then also generate the provided children.

Standalone Child Presets

If child components are represented by a model, you can also create presets for them. Using the example above, while a CardGrid preset could include Card presets, you could also have separate definitions for Card presets.

The benefit of this is that:

  1. When an editor adds the grid preset, they have some placeholder content for cards (rather than an empty space).
  2. Editors also have a series of options when creating new cards. After they've added a grid, they can then move quickly in adding new cards as needed.

Dynamic Content References

Some API CMSs don't have the concept of embedded models. For example, with Contentful, everything is a reference. Therefore, you must understand how to handle referenced content, as you may want to reuse existing content in some cases, but duplicate new records in other cases.

See the appropriate integration guide for your content source for more information.

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