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
js
let settingIcon = browser.browserAction.setIcon(
details // object
)
Parameters
details
-
object
. An object containing eitherimageData
orpath
properties, and optionally atabId
property.imageData
Optional-
orbrowserAction.ImageDataType
object
. This is either a singleImageData
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. IfimageData
is a dictionary, the value of each property is anImageData
object, and its name is its size, like this:json
{ 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
orobject
. 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:json
{ 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
andtabId
are both supplied, the function fails and the icon is not set. - If
windowId
andtabId
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
BCD tables only load in the browser
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.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:
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.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:
js
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.