Add-ons

browserAction.setIcon()

Sets the icon for the browser action.

You can specify a single icon as either the path to an image file or a browserAction.ImageDataType object.

You can specify multiple icons in different sizes by supplying a dictionary containing multiple paths or ImageData objects. This means the icon doesn't have to be scaled for a device with a different pixel density.

Tabs without a specific icon will inherit the global icon, which defaults to the default_icon specified in the manifest.

This is an asynchronous function that returns a Promise.

Syntax

var settingIcon = browser.browserAction.setIcon(
  details         // object
)

Parameters

details
object. An object containing either imageData or path properties, and optionally a tabId property.
imageDataOptional

browserAction.ImageDataType or object. This is either a single ImageData object or a dictionary object.

Use a dictionary object to specify multiple ImageData objects in different sizes, so the icon does not have to be scaled for a device with a different pixel density. If imageData is a dictionary, the value of each property is an ImageData object, and its name is its size, like this:

{
  16: image16,
  32: image32
}

The browser will choose the image to use depending on the screen's pixel density. See Choosing icon sizes for more information on this.

pathOptional

string or object. This is either a relative path to an icon file or it is a dictionary object. 

Use a dictionary object to specify multiple icon files in different sizes, so the icon does not have to be scaled for a device with a different pixel density. If path is a dictionary, the value of each property is a relative path, and its name is its size, like this:

{
  16: "path/to/image16.jpg",
  32: "path/to/image32.jpg"
}

The browser will choose the image to use depending on the screen's pixel density. See Choosing icon sizes for more information on this.

tabIdOptional
integer. Sets the icon only for the given tab. The icon is reset when the user navigates this tab to a new page. If this argument is omitted, the global icon is set instead.

If each one of imageData and path is one of undefined, null or empty object, then the tab-specific icon is removed so that the tab inherits the global icon in case a tabId is specified, otherwise the global icon is reverted to the default value.

Return value

A Promise that will be fulfilled with no arguments once the icon has been set.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes11445 No15
imageData23 No45 No15
The path and imageData properties of the details parameter can be set to null. No No59 No No

1. Before Chrome 23, `path` couldn't specify multiple icon files, but had to be a string specifying a single icon path.

Examples

The code below uses a browser action to toggle a listener for webRequest.onHeadersReceived, and uses setIcon() to indicate whether listening is on or off:

function logResponseHeaders(requestDetails) {
  console.log(requestDetails);
}

function startListening() {
  browser.webRequest.onHeadersReceived.addListener(
    logResponseHeaders,
    {urls: ["<all_urls>"]},
    ["responseHeaders"]
  );
  browser.browserAction.setIcon({path: "icons/listening-on.svg"});
}

function stopListening() {
  browser.webRequest.onHeadersReceived.removeListener(logResponseHeaders);
  browser.browserAction.setIcon({path: "icons/listening-off.svg"});
}

function toggleListener() {
  if (browser.webRequest.onHeadersReceived.hasListener(logResponseHeaders)) {
    stopListening();
  } else {
    startListening();
  }
}

browser.browserAction.onClicked.addListener(toggleListener);

The code below sets the icon using an ImageData object:

function getImageData() {
  var canvas = document.createElement("canvas");
  var ctx = canvas.getContext("2d");

  ctx.fillStyle = "green";
  ctx.fillRect(10, 10, 100, 100);
 
  return ctx.getImageData(50, 50, 100, 100);
}

browser.browserAction.onClicked.addListener(() => {
  browser.browserAction.setIcon({imageData: getImageData()});
});

The following snippet updates the icon when the user clicks it, but only for the active tab:

browser.browserAction.onClicked.addListener((tab) => {
  browser.browserAction.setIcon({
    tabId: tab.id, path: "icons/updated-48.png"
  });
});

Example extensions

Acknowledgements

This API is based on Chromium's chrome.browserAction API. This documentation is derived from browser_action.json in the Chromium code.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

Contributors to this page: wbamberg, Loirooriol, chaser, Makyen, chrisdavidmills
Last updated by: wbamberg,