MDN self-hosted library · e01.org

action.setIcon()

Sets the icon for the browser action.

Open notebook · 5 cells webextension-api-function upstream source

Sets the icon for the browser action.

[!NOTE] This API is available in Manifest V3 or higher.

You can specify a single icon as either the path to an image file or an action.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

let settingIcon = browser.action.setIcon(
  details         // object
)

Parameters

  • details
  • : object. An object containing the imageData or path property and, optionally, either or both of the tabId and windowId properties.

    • imageData
    • : action.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:

      js let settingIcon = browser.action.setIcon({ imageData: { 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.

    • path

    • : 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:

      js let settingIcon = browser.action.setIcon({ path: { 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.

    • tabId

    • : integer. Sets the icon only for the given tab. The icon is reset when the user navigates this tab to a new page.
    • windowId
    • : 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.

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.action.setIcon({ path: "icons/listening-on.svg" });
}

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

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

browser.action.onClicked.addListener(toggleListener);

The code below sets the icon using an ImageData object:

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

  ctx.fillStyle = "green";
  ctx.fillRect(10, 10, 100, 100);

  return ctx.getImageData(50, 50, 100, 100);
}

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

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

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

Browser compatibility

[!NOTE] This API is based on Chromium's chrome.action API. This documentation is derived from browser_action.json in the Chromium code.