Visual editing /Visual Editor /Visual editing /

Sidebar buttons

The sidebar buttons include triggers for Visual Editor’s primary editing capabilities but can also be extended to provide custom controls.

Standard and custom sidebar buttons.

# Standard buttons

Aside from the logo (which navigates back to the dashboard), the sidebar has a few standard buttons that cannot be altered:

# Custom buttons

Custom buttons can be added to the sidebar buttons that perform the following actions:

These behaviors are enabled by specifying the type of button in the sidebarButtons configuration property.

# Content editing shortcuts

When viewing a page within the preview, typically most of the editable content is available within the context of the current page. And the page editor will adjust itself for the context of the current page.

However, there may be objects that should always be available, as they would affect the content or styling of any page. This might include layout-based content for the header and footer, or other global settings like default SEO values or base-level global styles.

In most cases, these shortcuts are used for either single instance page models or data objects (which are also single instance models). In these cases, type should be set to model, and the appropriate modelName should be specified.

// stackbit.config.js
export default {
  sidebarButtons: [
    {
      label: "Site management",
      type: "model",
      icon: "tools",
      modelName: "SiteConfig"
    }
  ]
};

# Identify documents

Alternatively, you can use the ID. This is particularly helpful when targeting a single document within a model containing multiple documents.

// stackbit.config.js
export default {
  sidebarButtons: [
    {
      label: "Specific document",
      type: "document",
      icon: "user-management",
      documentId: "content/data/config.json"
    }
  ]
};

Identifying the document is unique to the content source. Each content source module must normalize the id property of a document when transforming it for use in Visual Editor. Unless otherwise noted in the content source guides, this is likely the same value used to uniquely identify the object within the content source.

# Multiple content sources

When using more than one content source, you must specify srcType and srcProjectId, alongside the other properties.

// stackbit.config.js
export default {
  sidebarButtons: [
    {
      label: "Document in specific content source",
      type: "document",
      icon: "user-management",
      documentId: "hGa71n3gba8",
      srcType: "contentful",
      srcProjectId: process.env.CONTENTFUL_SPACE_ID
    }
  ]
};

These values are provided by the content source as getContentSourceType and getProjectId.

When in an editing context, teams often bring in meta information or other hidden content to help make managing their site easier. For example, there may be an analytics dashboard on a page that is only visible in development mode.

In this case, providing a relative path to that page is enough for a button to navigate directly to it.

// stackbit.config.js
export default {
  sidebarButtons: [
    {
      label: "Internal page",
      type: "link",
      icon: "analytics",
      url: "/internal-page"
    }
  ]
};

# Open external URL

Opening external URLs work similarly. If Visual Editor finds a domain or full URL, it will open an external URL, rather than trying to navigate within the site.

// stackbit.config.js
export default {
  sidebarButtons: [
    {
      label: "External link",
      type: "link",
      icon: "external-link",
      url: "my-live-site.com"
    }
  ]
};

# Choose icons

Icons can be chosen from a list of available icons. These are listed in the sidebarButtons reference.

# Troubleshoot custom buttons

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

  1. The type is set to model, document, or link.
  2. 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.
  3. If using type: "document", ensure the documentId is in exactly the same format as you're using for inline editing annotations.
  4. For internal links (type: "link"), the url must be set to a relative URL.