Adding a Button to the Toolbar

To follow this tutorial you'll need to have installed the SDK and learned the basics of cfx.

This tutorial uses the action button API, which is only available from Firefox 29 onwards.

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

Create a new directory, navigate to it, and execute cfx init.

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

icon-16.png
icon-32.png
icon-64.png

Then open the file called "main.js" in the "lib" 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) {
  tabs.open("https://www.mozilla.org/");
}

Now run the add-on with cfx 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 https://www.mozilla.org/ 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

Attachments

File Size Date Attached by
icon-16
1657 bytes 2014-04-08 15:48:41 wbamberg
icon-32
3457 bytes 2014-04-08 15:48:49 wbamberg
icon-64
8635 bytes 2014-04-08 15:48:56 wbamberg
mozilla-button
31239 bytes 2014-04-08 16:09:44 wbamberg

Document Tags and Contributors

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