Component Presets

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

Component presets are predetermined variations of content that can be used to provide content editors with a quick way to create new, rich components.

Because components are represented by content models, presets are defined against a specific model.

Component Preset Example
Component Preset Example

How Presets Work

Stackbit looks for presets defined in the .stackbit/presets directory. (This can be customized using the presetSource option.)

These preset definitions are read by Stackbit, and the results displayed when a content editor chooses to create a new component, as shown in the image above.

Preset File Structure

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

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 .stackbit/presets directory.
  2. Generates a thumbnail preview of the component, and places the file in the .stackbit/presets/images directory.

Building Presets from Scratch

Because presets are stored as JSON files in your project (or as a shared package), 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

The presetSource option made 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

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 Child Components

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.

Save Page as Preset

Currently, the ability to create presets through the Stackbit application is limited to in-page components. However, because presets are applied to individual models and stored as JSON files, you can define presets for pages, as long as the page is represented by a model.

Even though you have to create page presets manually, they will still appear as options when a content editor creates a new page.

Pro Tip

Be sure to add a thumbnail images to your presets when creating manually so your editors know what to expect when adding a new page.