action.setIcon()
================

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 a `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
------


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

### Parameters

`details`

`object`. An object containing either `imageData` or `path` properties, and optionally a `tabId` property.

`imageData` Optional

``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` Optional

`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` Optional

`integer`. Sets the icon only for the given tab. The icon is reset when the user navigates this tab to a new page.

`windowId` Optional

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


```js
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:


```js
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:


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

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.action` API. This documentation is derived from `browser_action.json` in the Chromium code.