Adding Sidebar Buttons

New Feature

Sidebar button configuration is a new feature. It replaces the styleObjectModelName property with more powerful functionality.

Project with four custom buttons, with an editor-only page open.

You can add custom sidebar buttons that perform the following:

Navigate to a specific page in your website. This is especially useful for utility pages that are available to content editors but not included in the production build, e.g. site configuration, 3rd-party tool settings, a style guide page, etc.
A shortcut to an external URL, e.g. your live site which you host, or related tools that used by the content team.
Open a specific content item for editing, either by its content ID or by its model name.

Adding buttons#

`sidebarButtons`#

Holds an array of one or more objects, each representing one button. Here's an example showing all button types:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

export default {
  sidebarButtons: [
    // Open a content object for editing, by its model name
    {
      label: 'Site management',
      type: 'model',
      icon: 'tools',
      modelName: 'SiteConfig',
    },
    // Open a content object for editing, by its id
    {
      label: 'Specific document',
      type: 'document',
      icon: 'user-management',
      documentId: 'content/data/config.json',
    },
    // Open a content object by id, if using multiple content sources
    {
      label: 'Document in specific content source',
      type: 'document',
      icon: 'user-management',
      documentId: 'hGa71n3gba8',
      // Assuming ContentfulContentSource and a `CONTENTFUL_SPACE_ID` env. variable
      srcType: 'contentful', // or e.g. 'sanity'
      srcProjectId: process.env.CONTENTFUL_SPACE_ID,
    },
    // Navigate to a page in this site, by relative URL
    {
      label: 'Internal page',
      type: 'link',
      icon: 'analytics',
      url: '/internal-page',
    },
    // Open an external URL in a new tab
    {
      label: 'External link',
      type: 'link',
      icon: 'external-link',
      url: 'my-live-site.com',
    },
  ],
  // other properties ...
}

Required

Allowed Values

For each object in the array:

type (required): One of model, document, link.

For buttons of type model: a modelName property is required. When the button is clicked, a content item of that model name will be located and opened for editing. (note: there should be only one content item of that type)
For type document: a documentId property is required. This sets the ID of the object to open for editing (this is the same identifier used with the data-sb-object-id annotation)
For the above types: if your project uses multiple content sources you should also set srcType and srcProjectId to refer to the appropriate content source for the model or document you specified, as in the example above.
For type link: a url property is required. When set to a relative URL (beginning with /), the visual editor will navigate to this page. When set to an absolute URL, with or without protocol (e.g. https://some-site.com or some-site.com), that URL will be opened in a new tab.

label (optional): The tooltip label for the button.

icon (optional): One of the predefined icon names available for buttons. See list below.

Default

Available icons#

The following icons are available:

style
add-new
add-new-gear
analytics
external-link
global-objects
insights
personalization
search-settings
seo
tools
user-management

Troubleshooting#

In case a button does not work as expected, check the following:

The type is set to one of the supported values (see above)
If using type: "model", the modelName value must be set to exactly the model's name in the CMS. It is common for CMS's to have both a display name and a fixed identifier for models. The latter is what you need, and it is typically case-sensitive.
If using type: "document", ensure the documentId is in exactly the same format as you're using for annotations.
For interal links (type: link), the url must be set to a relative URL.

Deprecated properties#

`styleObjectModelName`#

This property sets the model name of a content item storing the site's global styles.

If set to a valid model name, a button will appear in the sidebar, labeled "Global styles". When clicked, the visual editor will look for a content item of that model name and open it for editing. The current page is not changed, so that you can edit styles and see the effect of your changes on whatever page you have open.

While this property is still supported, you can now achieve similar functionality by defining a sidebar button:

1
2
3
4
5
6
7
8
9
10
11

export default {
  sidebarButtons: [
    {
      type: 'model',
      label: 'Global styles',
      icon: 'style',
      modelName: 'GlobalStylesConfig',
    },
  ],
  // other properties ...
}