We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

Add-ons

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 omit the tabId option to setIcon(), then this sets the "global icon". The global icon will then appear in all tabs that do not have a tab-specific icon set.

Syntax

var settingIcon = browser.sidebarAction.setIcon(
  details         // object
)

Parameters

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

sidebarAction.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:

{
  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.

pathOptional

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.

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 is null, and tabId 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 is null, and tabId was omitted, and there was a global icon set, it will be reset to the manifest icon.

tabIdOptional
integer. Sets the icon only for the specified tab.
If this is omitted, the icon is updated for all tabs.

Return value

A Promise that will be fulfilled with no arguments once the icon has been set.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support No No54 No Yes
The path and imageData properties of the details parameter can be set to null. No No59 No No
details.windowId No No61 No No

Examples

The code below toggles the sidebar icon for the active tab when the user clicks a browser action:

var 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);

Acknowledgements

This API is based on Opera's chrome.sidebarAction API.

Document Tags and Contributors

Contributors to this page: ExE-Boss, wbamberg
Last updated by: ExE-Boss,