To edit your site visually in Stackbit, you must annotate your components. These annotations inform Stackbit how to map your site's data fields to the locations these fields are rendered on the screen.

It is important to annotate all the objects and fields in components used on your site's pages. Stackbit uses these annotations to allow content editors to edit any part of your site on top of the preview. If an object, or one of its fields, contributing to the page rendering is not specified with annotations, the content editor will not be able to edit that object when viewing that page in Stackbit.

Annotation Prerequisites

Before adding annotations, make sure you defined the models describing your site's content structure. Learn more here.

Note that Stackbit's default themes and their components bring their own stackbit.yaml config files.

If you use API-based CMS you don't need to define the models. Instead, annotations must match your site's models and their fields exactly.

Annotation Methods

There are two methods for making Stackbit components visually editable by annotating them:

  1. HTML data attributes
  2. React utility methods

HTML Data Attribute Annotations

The default method for annotating Stackbit components is using the HTML data attributes data-sb-object-id and data-sb-field-path. These are explained in more detail in the pages listed below.

data-sb-object-id

data-sb-object-id represents the a unique value that points to the data source.

data-sb-field-path

data-sb-field-path maps fields within a data object to elements within a component.

React Utility Methods

Stackbit provides utility methods that eliminate the need to use data attributes, along with the added benefit of removing this extra content from your application in production. The page listed outlines explains these methods in more detail.

React Annotation Utilities

Quick Example

The following example shows how data attributes can be used to annotate a React component to map the locations of your data fields. Dig into the links shared above to better understand the format of data-sb-* attributes.

function Post(props) {
  return (
    <article data-sb-object-id={props.post.id}>
      <h1 data-sb-field-path="title">{props.post.title}</h1>
      <img data-sb-field-path="image_url#@src" src={props.post.image_url} />
      <div data-sb-field-path="author">
        <div data-sb-field-path=".first_name">{props.post.author.first_name}</div>
        <div data-sb-field-path=".last_name">{props.post.author.last_name}</div>
      </div>
      <div data-sb-field-path="markdown_content">{props.post.markdown_content}</div>
    </article>
  )
}

Stackbit annotations support the following data attributes and their aliases:

  • data-sb-object-id - alias: data-sb-oid, data-sbo
  • data-sb-field-path - alias: data-sb-fp, data-sbf

Legacy Support

Projects using a stackbit.yaml version of 0.3.x or lower will use automatic annotation inference. This is more magical, but less accurate and much slower. To enable annotations, bump the version of stackbit.yaml to 0.4.0 and then annotate all your components. Learn more about that process here.