In this lesson, we improve the productivity of content editors by introducing component presets.

This is a lesson within the Next.js + Markdown tutorial. Following it requires completing all previous steps. If you’re looking for more information on component presets, there are a number of resources to explore:

Understanding Content Presets

You can think of content presets as default values on steroids. They provide content editors with a visual and efficient means of pre-populating various permutations of components and pages.

In our example project, we have various content fields that can change both the style and layout of each section. For example, the hero component can have the image on the left with the default button.

Hero with image on left

But it can also have the image on the right and/or swap the button style.

Hero with image on right

As sites and their components grow more complex, presets come in handy because they provide a very specific starting point for a given component or page, enabling editors to work much faster.

Refer to the conceptual guide if you'd like to take a deeper look into presets.

Saving a Component as a Preset

Stackbit has a built-in method for storing a component as a preset. When highlighting a particular component, click the save as preset icon.

Save as preset button

Give the preset a name and add it to a group (you’ll have to create the first group).

Save as preset modal

Preset Configuration Files

Presets are stored in configuration files within your site’s repository in the .stackbit/presets directory.

When saving a component as a preset, Stackbit automatically writes a file in this directory, and even provides a thumbnail image of the component.

Take a look in the .stackbit/presets directory and open up the JSON file. You’ll see that it represents all the content for that section, including the embedded button entry with its ID value.

{
  "model": "hero",
  "presets": [
    {
      "label": "Hero Image Right",
      "thumbnail": "images/hero-hero-image-right-29ee.png",
      "metadata": {
        "categories": ["My Components"],
        "canDelete": true
      },
      "data": {
        "heading": "Can you make the perfect sandwich?",
        "body": "HandSandwich™️ is Central Southwestern Ohio's most highly attended sandwich-making class. Don't delay your ability to craft the perfect sandwich.",
        "image": {
          "$$ref": "o1G1j1B3fpZyVGa33M1zJ",
          "$$type": "__image_model"
        },
        "button": {
          "$$ref": "36U7omnF7aFEHjVKwEhJI7",
          "$$type": "button"
        },
        "theme": "imgRight"
      }
    }
  ]
}

Creating a New Component from a Preset

Presets come into play when creating new pages or components. If you now try to add a hero component, you’ll notice that you have an option to start from the new preset.

New component from preset

See below for more information on what happens with the embedded button component when creating a new component from a preset.

Adding Presets Manually

Because presets are driven by JSON files in the .stackbit/presets directory, you can add presets for any structured content, including pages.

Use the technical reference to ensure you’re using the proper structure for the JSON object. You can also follow this guide, which walks through the process of creating a preset from scratch.

Handling Preset References

Because all content that is embedded in an object is an entry in Contentful, Stackbit needs to know how to handle the entry when creating a new entry.

In our example above, if we create a new hero component from this preset, it would use the existing button as its button.

This may not be your desired behavior. You may want a new button created when adding a new hero. To do that, you can set presetReferenceBehavior to duplicateContents in your stackbit.yaml configuration file.

stackbitVersion: ~0.5.0
# ...
presetReferenceBehavior: duplicateContents

Now when you add a new hero component using the preset, you will also end up with a new button entry in contentful. Learn more about how presets work with Contentful.