MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

A sidebar is a pane that is displayed at the left-hand side of the browser window, next to the web page. The browser provides a UI that enables the user to see the currently available sidebars and to select a sidebar to display. For example, Firefox has a "View > Sidebar" menu. Only one sidebar can be shown at a time, and that sidebar will be displayed for all tabs and all browser windows.

The browser may include a number of built-in sidebars. For example, Firefox includes a sidebar for interacting with bookmarks:

Using the sidebar_action manifest.json key, an add-on can add its own sidebar to the browser. It will be listed alongside the built-in sidebars, and the user will be able to open it using the same mechanism as for the built-in sidebars.

Like a browser action popup, you specify the sidebar's contents as an HTML document. When the user opens the sidebar, its document is loaded into every open browser window. Each window gets its own instance of the document. When new windows are opened, they get their own sidebar documents as well.

You can set a document for a particular tab using the sidebarAction.setPanel() function. A sidebar can figure out which window it belongs to using the windows.getCurrent() API:

// sidebar.js
browser.windows.getCurrent({populate: true}).then((windowInfo) => {
  myWindowId = windowInfo.id;
});

This is useful if a sidebar wants to display different content for different windows. For an example of this, see the "annotate-page" example.

Sidebar documents get access to the same set of privileged JavaScript APIs that the add-on's background and popup scripts get. They can get direct access to the background page using runtime.getBackgroundPage(), and can interact with content scripts or native applications using messaging APIs like tabs.sendMessage() and runtime.sendNativeMessage().

Sidebar documents are unloaded when their browser window is closed or when the user closes the sidebar. This means that unlike background pages, sidebar documents don't stay loaded all the time, but unlike browser action popups, they stay loaded while the user interacts with web pages.

When an add-on that defines a sidebar is first installed, its sidebar will be opened automatically. This is intended to help the user understand that the add-on includes a sidebar. Note that it's not possible for add-ons to open sidebars programmatically: sidebars can only be opened by the user.

Specifying sidebars

To specify a sidebar, define the default document with the sidebar_action manifest.json key, alongside a default title and icon:

"sidebar_action": {
  "default_title": "My sidebar",
  "default_panel": "sidebar.html",
  "default_icon": "sidebar_icon.png"
}

You can change the title, panel, and icon programmatically using the sidebarAction API.

Title and icon are shown to the user in any UI provided by the browser to list sidebars, such as the "View > Sidebar" menu in Firefox.

Example

The webextensions-examples repo on GitHub contains several examples of WebExtensions that use a sidebar:

Document Tags and Contributors

Tags: 
 Contributors to this page: ericjung, hellosct1, rebloor, wbamberg
 Last updated by: ericjung,