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.
windowIdOptional
integer. Sets the icon for the given window.
  • If windowId and tabId are both supplied, the function fails and the icon is not set.
  • If windowId and tabId are both omitted, the global icon is set.

If each one of imageData and path is one of undefined, null or empty object:

  • If tabId is specified, and the tab has a tab-specific icon set, then the tab will inherit the icon from the window to which it belongs.
  • If windowId is specified, and the window has a window-specific icon set, then the window will inherit the global icon.
  • Otherwise, the global icon will be reset to the manifest icon.

Return value

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

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
Basic supportChrome Full support Yes
Notes
Full support Yes
Notes
Notes Before Chrome 23, `path` couldn't specify multiple icon files, but had to be a string specifying a single icon path.
Edge Full support 14
Notes
Full support 14
Notes
Notes This call is not persisted.
Notes The imageData parameter is not accepted.
Notes The path parameter is required.
Firefox Full support 45
Full support 45
No support 45 — 58
Notes
Notes Tab-specific icons are not cleared when a new page is loaded.
Opera Full support 15Firefox Android No support No
imageDataChrome Full support 23Edge No support NoFirefox Full support 45Opera Full support 15Firefox Android No support No
The path and imageData properties of the details parameter can be set to null.Chrome No support NoEdge No support NoFirefox Full support 59Opera No support NoFirefox Android No support No
details.windowIdChrome No support NoEdge No support NoFirefox Full support 62Opera No support NoFirefox Android No support No

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

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: Loirooriol, irenesmith, wbamberg, chaser, Makyen, chrisdavidmills
Last updated by: Loirooriol,