sidebarAction.setIcon()
Sets the icon for the sidebar.
You can specify a single icon as either the path to an image file or a sidebarAction.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.
This is an asynchronous function that returns a Promise
.
Types of icon
Your extension should specify an icon for the sidebar in the sidebar_action
manifest key. This is called the "manifest icon".
If you don't specify an icon in the sidebar_action
key, you get the browser's default icon. This is called the "default icon".
If you set a new icon using setIcon()
, and include the tabId
option, then the icon is set only for the given tab. This icon is called the "tab-specific icon".
If you set a new icon using setIcon()
, and include the windowId
option, then the icon is set only for the given window. This icon is called the "window-specific icon", and will appear in all tabs of that window that do not have a tab-specific icon set.
If you set a new icon using setIcon()
, and omit both the tabId
and windowId
options, then this sets the "global icon". The global icon will then appear in all tabs that do not have a tab-specific icon set and whose window does not have a window-specific icon.
Syntax
js
let settingIcon = browser.sidebarAction.setIcon(
details // object
)
Parameters
details
-
object
. An object with the following properties:imageData
Optional-
orsidebarAction.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.
If
path
is an empty string, the browser will use the default icon.If
path
is not empty but does not point to an icon file, then the icon is hidden.If
path
isnull
, andtabId
was specified, and the specified tab had a tab-specific icon set: then the tab-specific icon is reset to the global icon (if a global icon is set) or the manifest icon.if
path
isnull
, andtabId
was omitted, and there was a global icon set, it will be reset to the manifest icon. tabId
Optional-
integer
. Sets the icon only for the given tab. windowId
Optional-
integer
. Sets the icon only for the given window.
- If
windowId
andtabId
are both specified, the function fails and the icon is not set. - If
windowId
andtabId
are both omitted, the icon is set globally.
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 toggles the sidebar icon for the active tab when the user clicks a browser action:
js
let on = false;
function toggle(tab) {
if (on) {
browser.sidebarAction.setIcon({
path: "off.svg",
tabId: tab.id
});
on = false;
} else {
browser.sidebarAction.setIcon({
path: "on.svg",
tabId: tab.id
});
on = true;
}
}
browser.browserAction.onClicked.addListener(toggle);
Note: This API is based on Opera's chrome.sidebarAction
API.