browserAction.setIcon()

Sets the icon for the browser action. The icon can be specified either as the path to an image file, the pixel data from a <canvas> element, or a dictionary of either one of those. Either the path or the imageData property must be specified.

Syntax

browser.browserAction.setIcon(
  details         // object
)

Parameters

details
object.
imageDataOptional
browserAction.ImageDataType or object. Either an ImageData object or a dictionary {size -> ImageData} representing the icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then an image with size scale * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that details.imageData = foo is equivalent to details.imageData = {'19': foo}.
pathOptional
string or object. Either a relative image path or a dictionary {size -> relative image path} pointing to the icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on the screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then an image with size scale * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that details.path = foo is equivalent to details.imageData = {'19': foo}.
tabIdOptional
integer. Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

Browser compatibility

Chrome Edge Firefox Firefox for Android Opera
Basic support Yes Yes 45.0 No 33

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 add-ons

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