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
.
var settingIcon = browser.browserAction.setIcon( details // object )
details
object
. An object containing either imageData
or path
properties, and optionally a tabId
property.imageData
Optional
or browserAction.ImageDataType
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:
{ 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:
{ 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.windowId
and tabId
are both supplied, the function fails and the icon is not set.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:
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.windowId
is specified, and the window has a window-specific icon set, then the window will inherit the global icon.A Promise
that will be fulfilled with no arguments once the icon has been set.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
setIcon |
Yes
Before Chrome 23, `path` couldn't specify multiple icon files, but had to be a string specifying a single icon path.
|
14
["This call is not persisted.", "The
imageData parameter is not accepted.", "The path parameter is required."] |
45
45-58
Tab-specific icons are not cleared when a new page is loaded.
|
? |
15 |
14 |
? |
? |
79 |
? |
? |
? |
imageData |
23 |
79 |
45 |
? |
15 |
14 |
? |
? |
79 |
? |
? |
? |
null |
No |
No |
59 |
? |
No |
14 |
? |
? |
79 |
? |
? |
? |
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" }); });
Note: 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.
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction/setIcon