Adding a Button to the Toolbar

We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.

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 instead.

Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.

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

To follow this tutorial you'll need to have learned the basics of jpm.

To add a button to the toolbar, use the action button or toggle button modules.

Create a new directory, navigate to it, and execute jpm init, accepting all the defaults.

Create a directory called "data",

mkdir data

and save these three icon files to the "data" directory:


Then open the file called "index.js" in the root of your addon directory and add the following code to it:

var buttons = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");

var button = buttons.ActionButton({
  id: "mozilla-link",
  label: "Visit Mozilla",
  icon: {
    "16": "./icon-16.png",
    "32": "./icon-32.png",
    "64": "./icon-64.png"
  onClick: handleClick

function handleClick(state) {"");

Now run the add-on with jpm run. The button is added to the toolbar at the top of the browser window:

You can't set the initial location for the button, but the user can move it using the browser's customization feature. The id attribute is mandatory, and is used to remember the position of the button, so you should not change it in subsequent versions of the add-on.

Clicking the button loads into a new tab.

Specifying the icon

The icon property may specify a single icon or a collection of icons in different sizes, as in the example above. If you specify a collection of icons in different sizes the browser will automatically choose the best fit for the screen resolution and the place in the browser UI that hosts the button. Read more about specifying multiple icons.

The icon file must be packaged with your add-on: it may not refer to a remote file.

You can change the icon at any time by setting the button's icon property. You can change the icon, and the other state attributes, either globally, for a specific window, or for a specific tab. Read more about updating state.

Attaching a panel

If you need to attach a panel to a button, use the toggle button API. This is just like the action button API except it adds a boolean checked property which is toggled whenever the button is checked. To attach the panel, pass the button to the panel's show() method. For more details on this, see the toggle button's documentation.

Displaying richer content

To create more complex user interface content than is possible with just a button, use the toolbar API. With the toolbar API you get a complete horizontal strip of user interface real estate. You can add buttons to the toolbar and also frames, that can host HTML, CSS, and JavaScript.

Learning more

Document Tags and Contributors

 Contributors to this page: wbamberg, diorahman, shorteee, Koniii, mediocrity, Delapouite, Canuckistani
 Last updated by: wbamberg,