Sidebar

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

This page provides several snippets demonstrating how to work with the Firefox sidebar.

See the Creating a Firefox sidebar tutorial for step-by-step instructions on creating a Firefox sidebar extension.

Opening and closing the sidebar

Firefox provides a built-in SidebarUI object function defined in browser-sidebar.js. This means that the function is available in all browser windows. You can use this function to show, hide, or toggle sidebars.

// toggle the bookmarks sidebar (close it if it's open or
// open it if it's currently closed)
SidebarUI.toggle("viewBookmarksSidebar");
// show the history sidebar, whether it's hidden or already showing
SidebarUI.show("viewHistorySidebar");
// hide the sidebar, if one is showing
SidebarUI.hide();

Avoid opening the sidebar on startup. Users have been known to complain about this "feature", and if two or more extensions try to open their sidebars on startup, the user will see a flurry of sidebars opening and closing with which ever extension going last "winning".

Web panels sidebar

Content such as web pages can be safely loaded as sidebar in the "viewWebPanelsSidebar". Bookmarks with "Load this bookmark in sidebar" checked in the properties open in the "viewWebPanelsSidebar". A web page can use window.sidebar to create bookmark with that property. To open a page in the "viewWebPanelsSidebar" from chrome code (browser/addon/extension) such as from menuitem, it can call:
openWebPanel(aTitle, aURI);

Accessing the sidebar from a browser.xul script

The sidebar content is always in a document separate from the main browser document (the sidebar is actually implemented as a XUL browser element). This means you can't directly access the sidebar content from a script referenced from a browser.xul overlay.

To access your sidebar's window or document objects, you need to use the contentWindow or contentDocument properties of document.getElementById("sidebar") respectively. For example the code below calls a function defined in the sidebar's context:

var sidebarWindow = document.getElementById("sidebar").contentWindow;
// Verify that our sidebar is open at this moment:
if (sidebarWindow.location.href ==
      "chrome://yourextension/content/whatever.xul") {
  // call "yourNotificationFunction" in the sidebar's context:
  sidebarWindow.yourNotificationFunction(anyArguments);
}

Testing which sidebar is open

The sidebar content may contain different panels (bookmarks, history, webpanel, etc.) and sometimes one wants to only act on the sidebar when it contains a specific panel. The good practice to determine which sidebar is open at a time is by testing in location property, which is a chrome URL:

var sidebarWindow = document.getElementById("sidebar").contentWindow;
if (sidebarWindow.location.href == "chrome://yourextension/content/whatever.xul") {
  // Act on the sidebar content
}

For example to test if the web panel from Firefox is open:

var sidebarWindow = document.getElementById("sidebar").contentWindow;
if (sidebarWindow.location.href == "chrome://browser/content/web-panels.xul") {
  // Act on the sidebar content only if it is the web panels
}

Accessing the browser.xul window from a sidebar script

See Accessing the elements of the top-level document from a child window section of Working with windows in chrome code.

Resizing the sidebar programmatically

In case you need to change the width of the sidebar, use the following code:

function setSidebarWidth(newwidth) {
 var mainWindow = window.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
 .getInterface(Components.interfaces.nsIWebNavigation)
 .QueryInterface(Components.interfaces.nsIDocShellTreeItem)
 .rootTreeItem
 .QueryInterface(Components.interfaces.nsIInterfaceRequestor)
 .getInterface(Components.interfaces.nsIDOMWindow);
 mainWindow.document.getElementById("sidebar-box").width=newwidth;
}

function setSidebarWidth(newwidth) {
  window.top.document.getElementById("sidebar-box").width=newwidth;
}

You can also disable the ability to resize it manually, using the mouse, by hiding the sidebar's splitter element. For this snippet to work, you have to declare mainWindow as in the previous code block then write:

mainWindow.document.getElementById("sidebar-splitter").hidden = true;

Be aware that if you change the splitter's hidden attribute, you need to reset it to a safe value when your sidebar is closed, or replaced by another sidebar. For example, use this in your sidebar's Unload event handler:

mainWindow.document.getElementById("sidebar-splitter").hidden =
  mainWindow.document.getElementById("sidebar-box").hidden;