W3cubDocs

/Web Extensions

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

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
setIcon
Yes
Before Chrome 23, `path` couldn't specify multiple icon files, but had to be a string specifying a single icon path.
14
["This call is not persisted.", "The imageData parameter is not accepted.", "The path parameter is required."]
45
45-58
Tab-specific icons are not cleared when a new page is loaded.
?
15
14
?
?
79
?
?
?
imageData
23
79
45
?
15
14
?
?
79
?
?
?
null
No
No
59
?
No
14
?
?
79
?
?
?

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

Note: 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.

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction/setIcon