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

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

• bookmark-it