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

``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:


```js
let settingIcon = browser.action.setIcon({
  imageData: {
    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:


```js
let settingIcon = browser.action.setIcon({
  path: {
    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.

`tabId` Optional

`integer`. Sets the icon only for the given tab.

`windowId` Optional

`integer`. Sets the icon only for the given window.



* If `windowId` and `tabId` are both specified, the function fails and the icon is not set.
* If `windowId` and `tabId` 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 with JavaScript enabled. Enable JavaScript to view data.

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.