Adding a Button to the Toolbar

This is an archived page. It's not actively maintained.


Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.

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.

Starting from Firefox 53, no new legacy add-ons will be accepted on (AMO) for desktop Firefox and Firefox for Android.

Starting from Firefox 57, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

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 use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

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