ui/button/action

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.

Experimental

Add a button to the Firefox user interface. With this module you can create buttons that display icons and can respond to click events.

Usage


Creating buttons

To create a button you must give it an ID, an icon, and a label:

var { ActionButton } = require("sdk/ui/button/action");
var button = ActionButton({
    id: "my-button",
    label: "my button",
    icon: {
      "16": "./firefox-16.png",
      "32": "./firefox-32.png"
    },
    onClick: function(state) {
        console.log("button '" + state.label + "' was clicked");
    }
  });

By default, the button appears in the Firefox toolbar:

However, users can move it to the Firefox menu panel using the toolbar customization feature:

Badged buttons

New in Firefox 36.

You can add a "badge" to a button using its badge property. This can be a number or a string, and you can update it at any time. By default the badge's color is red, but you can set your own color using the badgeColor property, specified as a CSS <color> value:

var { ToggleButton } = require("sdk/ui/button/toggle");
var button = ToggleButton({
    id: "my-button1",
    label: "my button1",
    icon: "./icon-16.png",
    onChange: changed,
    badge: 0,
    badgeColor: "#00AAAA"
  });
function changed(state) {
  button.badge = state.badge + 1;
  if (state.checked) {
    button.badgeColor = "#AA00AA";
  }
  else {
    button.badgeColor = "#00AAAA";
  }
}

Specifying multiple icons

You can specify just one icon, or multiple icons in different sizes.

If you specify multiple icons, Firefox will select the best-fitting icon based on the device screen resolution and the place the icon appears. For example, in the screenshots above, Firefox uses the small icon when the button is in the toolbar and the large icon when the button is in the menu panel. Read more about specifying icons in the reference documentation for the ActionButton constructor.

Responding to click events

You can respond to click events by assigning a listener to the button's click event. You can do this in the button's constructor, by assigning the listener to the onClick option. You can also add, or change, the listener afterwards:

var { ActionButton } = require("sdk/ui/button/action");
var button = ActionButton({
    id: "my-button",
    label: "my button",
    icon: {
      "16": "./firefox-16.png",
      "32": "./firefox-32.png"
    },
    onClick: firstClick
  });
function firstClick(state) {
  console.log("You clicked '" + state.label + "'");
  button.removeListener("click", firstClick);
  button.on("click", subsequentClicks);
}
function subsequentClicks(state) {
  console.log("You clicked '" +  state.label + "' again");
}

The listener is passed a state object that contains all the button's properties.

You can generate click events programmatically with the button's click() method.

Disabling buttons

You can disable a button by setting its disabled property to true. A disabled button will not generate click events and its icon will appear disabled:

Updating state

You can update all the button's properties except for its id.

By default, the button has global state: that is, its properties are the same across all open windows and tabs, and updating them updates the button's state across all open windows and tabs.

You can set state to be specific to a window or tab using the button's state() method. To set state like this, call state() with 2 parameters:

  • the first parameter is a window or tab object or as a shorthand, the string "window" for the currently active window, or the string "tab" for the currently active tab
  • the second parameter is an object containing the state properties you wish to update.

Here's an add-on with a button that disables itself when you click it, but only for the currently active window:

var { ActionButton } = require("sdk/ui/button/action");
var button = ActionButton({
    id: "my-button",
    label: "my button",
    icon: {
      "16": "./firefox-16.png",
      "32": "./firefox-32.png"
    },
    onClick: disableForThisWindow
  });
function disableForThisWindow(state) {
  button.state("window", {
    disabled: true
  });
}

To fetch the state for a specific window or tab, call state(), passing in the window or tab you are interested in, and it will return the state:

var labelForActiveTab = button.state("tab").label;

To learn more about this, see the API documentation for state().

Destroying buttons

When you've finished with a button, destroy it by calling its destroy() method. After that, any attempts to access any of its properties or to call any of its methods will throw exceptions.

Globals

Constructors

ActionButton(options)

Creates an action button.

Parameters

options : object
Required options:

Name Type  
id string

The button's ID. This is used internally to keep track of this button. The ID must be unique within your add-on.

label string

The button's human-readable label. When the button is in the toolbar, this appears in a tooltip, and when the button is in the menu, it appears underneath the button as a legend.

icon url, string, object

One or more icons for the button. You can specify this in one of three ways: 

  • as a resource:// URL pointing at an icon file in your add-on's "data" directory, typically constructed using self.data.url(iconfile)
  • as a relative path: a string in the form "./iconfile", where "iconfile" is a relative path to the icon file beginning in your add-on's "data" directory
  • as an object, or dictionary of key-value pairs. Here you can specify a range of sizes for your button's icon. Each key-value pair specifies an icon:
    • each value specifies an image file as a resource:// URL or relative path.
    • each key must be a numeric string such as "16", or "32", which represents the size in pixels of the corresponding image.
var { ActionButton } = require('sdk/ui/button/action');
var self = require("sdk/self");
var button1 = ActionButton({
    id: "my-button1",
    label: "my button1",
    icon: self.data.url("firefox-16.png")
  });
var button2 = ActionButton({
    id: "my-button2",
    label: "my button2",
    icon: "./firefox-16.png"
  });
var button3 = ActionButton({
    id: "my-button3",
    label: "my button3",
    icon: {
      "16" : "./firefox-16.png",
      "32" : "./firefox-32.png",
      "64" : "./firefox-64.png"
    }
  });

If you use the final form, Firefox will automatically choose the best-fit icon for your button, depending on the device screen resolution and where the button is in the UI. On a device with a "normal" screen resolution, the toolbar has space for 18 x 18 pixels and the menu panel has space for 32 x 32 pixels. On a high resolution screen (such as a HiDPI display), these are doubled to 36 x 36 and 64 x 64 pixels, respectively. So you can supply three icon files:

icon: {
  "16": "./addon16.png",
  "32": "./addon32.png",
  "64": "./addon64.png"
}

This will look fine in both toolbar and menu panel, and for both screen resolutions. However, the icons in the toolbar will not quite fill the space available, so you can instead supply four icons:

icon: {
  "18": "./addon18.png", // toolbar icon non HiDPI
  "32": "./addon32.png", // menu panel icon non HiDPI
  "36": "./addon36.png", // toolbar icon HiDPI
  "64": "./addon64.png"  // menu panel icon HiDPI
}

Optional options:

Name Type  
disabled boolean

Determines whether the button is disabled. Disabled buttons appear disabled in the UI, and do not respond to clicks. Defaults to false.

onClick function

Click handler for the button.

badge Number or String

New in Firefox 36.

Badge to attach to the button.

The badge can contain as many characters (or digits) as you like, but only the first four will be displayed.

badgeColor CSS <color> value

New in Firefox 36.

Color for the badge. If badgeColor is omitted and badge is specified, then the badge is red.

ActionButton

Methods

click()

Click the button. This will cause the button to generate the click event:

var { ActionButton } = require('sdk/ui/button/action');
var button = ActionButton({
  id: "my-button",
  label: "my button",
  icon: {
    "16": "./firefox-16.png",
    "32": "./firefox-32.png"
  },
  onClick: function(state) {
      console.log("You clicked '" + state.label + "'");
  }
});
button.click();

state()

Get or set the button's state for a specific window or tab.

By default, a button's properties are global, meaning that they are the same across all open windows and tabs, and that if you update these properties, then they are updated across all windows and tabs. But sometimes you want a button attached to one window (or tab) to have a different state to a button attached to a different window (or tab). That's what state() is for.

To set a button's properties for a specific window or tab, call state(), passing it the window or tab you want the property to apply to, and the property value to set. A special shortcut allows you to pass the string "window" or "tab" to select the currently active window or tab.

For example, if you have a button like this:

var { ActionButton } = require('sdk/ui/button/action');
var button = ActionButton({
  id: "my-button",
  label: "default",
  icon: "./firefox-16.png"
});

You can change its label for only the currently active window like this:

button.state("window", {
  "label" : "window-specific label"
});

You can change its label for only the currently active tab like this:

button.state("tab", {
  "label" : "tab-specific label"
});

To fetch the button state for a specific window or tab, call state(), passing it the window or tab you're interested in, and it will return a state object containing all the properties for the button associated with that window or tab. Again. you can use the strings "window" or "tab" as shortcuts. For example, this add-on:

  • creates a button with a default label
  • opens a new tab
  • sets a new label only for the new tab
  • logs the result of accessing the global label, the window-specific label, and each of the 2 tab-specific labels
var { ActionButton } = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");
var button = ActionButton({
  id: "my-button",
  label: "default label",
  icon: "./firefox-16.png"
});
tabs.open({
  url: "https://mozilla.org/",
  onOpen: onNewTab
});
function onNewTab(tab) {
  // Modify the label only for the new tab
  button.state(tab, {
    "label" : "tab-specific label"
  });
  // access the global label -> "default label"
  console.log(button.label);
  // access the window's label -> "default label"
  console.log(button.state("window").label);
  // access the first tab's label -> "default label"
  console.log(button.state(tabs[0]).label);
  // access the second tab's label -> "tab-specific label"
  console.log(button.state(tabs[1]).label);
}

Setting a property won't affect a more-specific property setting. For example, if you have a window with two tabs, and you set a tab-specific label, then set the window-specific label, this will not overwrite the tab-specific label:

var { ActionButton } = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");
var button = ActionButton({
  id: "my-button",
  label: "default label",
  icon: "./firefox-16.png"
});
tabs.open({
  url: "https://mozilla.org/",
  onOpen: onNewTab
});
function onNewTab(tab) {
  // Modify the label only for the new tab
  button.state(tab, {
    "label" : "tab-specific label"
  });
  // Modify the label for the window
  button.state("window", {
    "label" : "window-specific label"
  });
  // access the global label -> "default label"
  console.log(button.label);
  // access the window's label -> "window-specific label"
  console.log(button.state("window").label);
  // access the first tab's label -> "window-specific label"
  console.log(button.state(tabs[0]).label);
  // access the second tab's label -> "tab-specific label"
  console.log(button.state(tabs[1]).label);
}

The best way to think of this is as a tree: the global state is the root, followed by the state for each window, followed by the state for each tab in a window. If a property value for a node in the tree has not been set explicitly using state(), then it inherits its value from the next level up. So if you have one window containing two tabs, and have set the button's label only for tab A, then tab B will inherit label's value from the window, and changing the value for the window will implicitly change the value for tab B.

To delete a tab- or window-specific state, assign null to the property. After that, the property will inherit its value from the less-specific state as before:

var { ActionButton } = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");
var button = ActionButton({
  id: "my-button",
  label: "default label",
  icon: "./firefox-16.png"
});
tabs.open({
  url: "https://mozilla.org/",
  onOpen: onNewTab
});
function onNewTab(tab) {
  // Modify the label only for the new tab
  button.state(tab, {
    "label" : "tab-specific label"
  });
  // Modify the label for the window
  button.state("window", {
    "label" : "window-specific label"
  });
  // access the global label -> "default label"
  console.log(button.label);
  // access the window's label -> "window-specific label"
  console.log(button.state("window").label);
  // access the first tab's label -> "window-specific label"
  console.log(button.state(tabs[0]).label);
  // access the second tab's label -> "tab-specific label"
  console.log(button.state(tabs[1]).label);
  // Reset the tab-specific state
  button.state(tab, null);
  // access the second tab's label -> "window-specific label"
  console.log(button.state(tabs[1]).label);
}

Finally, you can pass the button itself into state(). This is an alternative way to set or get the global state. The reason for using this, rather than setting properties individually, is that you can define an object with the properties to set in one place, then apply it to the global state with a single line:

const defaultState = {
  "label": "default label",
  "icon": "./default.png",
}
const differentState = {
  "label": "different label",
  "icon": "./different.png",
}
var { ActionButton } = require("sdk/ui/button/action");
var button = ActionButton({
    id: "default-label",
    label: "default label",
    icon: "./default.png",
    onClick: function(state) {
      if (button.label == "default label") {
        button.state(button, differentState);
      }
      else {
        button.state(button, defaultState);
      }
      console.log(button.state(button).label);
      console.log(button.state(button).icon);
    }
  });
Parameters

target : button, tab, window, string

  • To set or get the global state, this needs to be the button instance.
  • To get or set window-specific state, this needs to be the window object for which you wish to set a specific state, or the string "window" to select the currently active window.
  • To get or set tab-specific state this needs to be the tab object for which you wish to set a specific state, or the string "tab" to select the currently active tab.

state : object, null
Include this parameter only if you are setting state. It is an object containing all the properties you wish to set. For example:

button.state("tab", {
  "label" : "tab-specific label",
  "icon": "./tab-specific-icon.ico"
});

To reset state, pass null:

button.state("tab", null);
Returns

state : if you have passed the second state argument to make this function a setter, it returns undefined. Otherwise, it functions as a getter and returns the button's state for the specified object. This logs the state for the button associated with the currently active tab:

console.log(button.state("tab"));

This object represents a snapshot of the state at the time state() is called. It is not kept up to date with changes made to the button:

button.label = "foo";
var state = button.state(button);
button.label = "bar";
console.log(state.label) // foo

on()

Add a listener to an event emitted by the button. The button only emits one type of event, click:

button.on("click", handleClick)
function handleClick(state) {
  console.log("button '" + state.label + "' was clicked");
}
Parameters

event : string
The event to listen for. Action buttons only emit one type of event, "click".

listener : function
Function that will be called on click.

once()

Assign a listener to the first occurrence only of an event emitted by the button. The button only emits one type of event, click. The listener is automatically removed after the first time the event is emitted.

Parameters

event : string
The event to listen for. Action buttons only emit one type of event, "click".

listener : function
Function that will be called on click.

removeListener()

Removes an event listener. For example, this code is equivalent to once():

button.on("click", handleClick)
function handleClick(state) {
  console.log("button '" + state.label + "' was clicked");
  button.removeListener("click", handleClick);
} 
Parameters

event : string
The event to listener is listening for. Action buttons only emit one type of event, "click".

listener : function
The listener to remove.

destroy()

Destroy the button. After calling this function, the button will no longer appear in the UI, and accessing any of its properties or methods will throw an error.

Properties

id

The button's unique ID. This is read-only.

label

The button's label.

icon

The button's icon or icons, as a URL, relative path, or object containing a set of key-value pairs.

disabled

Boolean property indicating whether or not the button is disabled.

badge

New in Firefox 36.

Value to attach to the button as a badge. May be a number or a string.

The badge can contain as many characters (or digits) as you like, but only the first four will be displayed.

badgeColor

New in Firefox 36.

Color for the badge, specified as a CSS <color> value.

Events

click

This event is emitted when a user clicks the button or your add-on calls the button's click() method.

Arguments

state : The button's state. This contains all the button's properties.

Document Tags and Contributors

 Contributors to this page: wbamberg, addOn
 Last updated by: wbamberg,