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 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:{ 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:{ 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
Optionalinteger
. Sets the icon only for the given tab. The icon is reset when the user navigates this tab to a new page.windowId
Optionalinteger
. 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
Report problems with this compatibility data on GitHubwebextensions-desktop | webextensions-mobile | |||||
---|---|---|---|---|---|---|
setIcon | ChromeFull supportYes
| EdgeFull support14
| FirefoxFull support45
| OperaFull support15 | SafariFull support14 | Firefox for AndroidFull support79 |
imageData | ChromeFull support23 | EdgeFull support79 | FirefoxFull support45 | OperaFull support15 | SafariFull support14 | Firefox for AndroidFull support79 |
The path and imageData properties of the details parameter can be set to null . | ChromeNo supportNo | EdgeNo supportNo | FirefoxFull support59 | OperaNo supportNo | SafariFull support14 | Firefox for AndroidFull support79 |
Legend
- Full support
- Full support
- No support
- No support
- See implementation notes.
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
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.