@stackbit/annotations

Stackbit Annotations

This package includes several utilities to work with Stackbit annotations in React.

Stackbit annotations enable on-page editing experience for your site. Click here to learn more about Stackbit.

Install

npm install @stackbit/annotations

Usage

import * as React from 'react';
import { toObjectId, toFieldPath } from '@stackbit/annotations';

export function MyComponent(props) {
  return (
    <div {...toObjectId(props.id)}>
       <h1 {...toFieldPath('title')}>{props.title}</h1>
       <img src={props.image} {...toFieldPath('image#@src')} />
       {props.link && (
         <a href={props.link.url} {...toFieldPath('link.url#@href', 'link.text')}>
           {props.link.text}
         </a>
       )}
    </div>
  );
}

Output:

<div data-sb-object-id="...">
   <h1 data-sb-field-path="title">...</h1>
   <img src="..." data-sb-field-path="image#@src" />
   <a href="..." data-sb-field-path="link.url#@href link.text">...</a>
</div>

When NODE_ENV is set to production, toObjectIds and toFieldPath will return empty objects, effectively removing any Stackbit annotations.

Utilities

toObjectId

Takes a string and returns an object with that string inside the data-sb-object-id property. When NODE_ENV is set to production, this function returns an empty object.

toObjectId('xyz');
// result: { 'data-sb-object-id': 'xyz' }

toFieldPath

Takes field-path and returns an object with all field-paths concatenated into the data-sb-field-path property. Each field-path can be a string or a FieldPathDescriptor. When NODE_ENV is set to production, this function returns an empty object.

toFieldPath('title', { objectId: 'xyz', fieldPath: 'url', xpath: '@href' });
// result: { 'data-sb-field-path': 'title xyz:url#@href' }

getObjectId

Takes an object and returns the value of the data-sb-object-id property if it exists, otherwise returns undefined.

getObjectId({ 'data-sb-object-id': 'xyz' });
// result: 'xyz'

getFieldPath

Takes an object and returns the value of the data-sb-field-path property if it exists, otherwise returns undefined.

getFieldPath({ 'data-sb-field-path': 'title' });
// result: 'title'

pickDataAttrs

Takes an object and returns a new object with only the properties that start with data-

getFieldPath({
    foo: 'bar',
    bar: 'foo',
    'data-sb-object-id': 'xyz',
    'data-sb-field-path': 'title'
});
// result:
// {
//   'data-sb-object-id': 'xyz',
//   'data-sb-field-path': 'title'
// }