@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' // }