data-sb-object-id is an annotation method used to scope an HTML element to a particular data object. This makes your components visually editable in Stackbit when used in conjunction with data-sb-field-path (link).

Scoping Data Objects

The value of the data-sb-object-id represents a unique ID of an object in the data source (more on this below). Applying the attribute establishes a scope from which all nested elements can extract field paths from that object.

This is particularly useful when a component (or series of HTML elements) renders most of an object's fields.

Consider a simple data object that looks like this:

{
  "title": "Hello World"
}

After obtaining the ID value for this object, we can then use data-sb-field-path to annotate individual fields and make it possible to visually edit this content in Stackbit.

<div data-sb-object-id="some-id">
  <h2 data-sb-field-path="title">{ title }</h2>
</div>

Finding the Object ID

When working with data stored in local files (markdown, JSON, YAML, etc.), the data-sb-object-id should be the file path of that file relative to the project root folder.

For example, assume you have a data directory in the root of your project, with a products subdirectory that stores product data as JSON files. The structure looks like this:

.
└── data
    └── products
        ├── orange.json
        └── apple.json

And orange.json might look something like this:

{
  "title": "Orange",
  "slug": "orange",
  "image_url": "/images/orange.png",
  "description": "Oranges are a healthy source of fiber, vitamin C, thiamine, folate, and antioxidants.",
  "price": 49
}

And let's say your site lists these products using a <ProductCard> component. To let Stackbit know that the data rendered within the <ProductCard> component belongs to a particular product, you need to set the data-sb-object-id attribute to the appropriate value. In this case, that value is data/products/orange.json.

How you obtain this value dynamically depends on the SSG you're using. Stackbit's current themes are built with Next.js, which is described below.

Stackbit themes (built with Next.js) rely on the sourcebit-source-filesystem plugin to get the file path of the underlying object, which provides a __metadata.id property.

Stackbit's use of Sourcebit is nearing the end of its life. Expect this document to change in the near future.

The implementation could look something like this:

export default function ProductCard(props) {
  const product = props.product;
  return (
		<a data-sb-object-id={product.__metadata.id}
       class="product-card"
       href={`/products/${ product.slug }`}>
		  <div>{ product.title }</div>
		  <img src={ product.image_url } />
		  <div>{ product.description }</div>
		  <div>
		    <span>$</span>
		    <span>{ product.price }<span>
		  </div>
		</a>
  );
}

Using data-sb-object-id with API-based CMS

When working with data stored in an API-based CMS, the object ID will be provided by the CMS and will be accessible as a special field. For example, in Contentful it is stored as sys.id and in Sanity it is stored as _id. All you need to do is to set the data-sb-object-id to the field storing the object ID.