recursal/MDN huggingface dataset:
browserAction.setPopup()
========================

Sets the HTML document that will be opened as a popup when the user clicks on the browser action's icon. Tabs without a specific popup will inherit the global popup, which defaults to the `default_popup` specified in the manifest.

Syntax
------


```js
browser.browserAction.setPopup(
  details // object
)
```

### Parameters

`details`

An object with the following properties:

`tabId` Optional

`integer`. Sets the popup only for a specific tab. The popup is reset when the user navigates this tab to a new page.

`windowId` Optional

`integer`. Sets the popup only for the specified window.

`popup`

`string` or `null`. The HTML file to show in a popup, specified as a URL.

This can point to a file packaged within the extension (for example, created using `extension.getURL`), or a remote document (e.g. `https://example.org/`).

If an empty string (`""`) is passed here, the popup is disabled, and the extension will receive `browserAction.onClicked` events.

If `popup` is `null`:

* If `tabId` is specified, removes the tab-specific popup so that the tab inherits the global popup.
* If `windowId` is specified, removes the window-specific popup so that the window inherits the global popup.
* If `tabId` and `windowId` are both omitted, reverts the global popup to the default value.



* If `windowId` and `tabId` are both supplied, the function fails and the popup is not set.
* If `windowId` and `tabId` are both omitted, the global popup is set.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This code adds a pair of context menu items that you can use to switch between two popups. Note that you'll need the "contextMenus" permission set in the extension's manifest to create context menu items.


```js
function onCreated() {
  if (browser.runtime.lastError) {
    console.log("error creating item:", browser.runtime.lastError);
  } else {
    console.log("item created successfully");
  }
}

browser.contextMenus.create(
  {
    id: "popup-1",
    type: "radio",
    title: "Popup 1",
    contexts: ["all"],
    checked: true,
  },
  onCreated,
);

browser.contextMenus.create(
  {
    id: "popup-2",
    type: "radio",
    title: "Popup 2",
    contexts: ["all"],
    checked: false,
  },
  onCreated,
);

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "popup-1") {
    browser.browserAction.setPopup({ popup: "/popup/popup1.html" });
  } else if (info.menuItemId === "popup-2") {
    browser.browserAction.setPopup({ popup: "/popup/popup2.html" });
  }
});
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.onClicked
=======================

Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.

To define a right-click action, use the `contextMenus` API with the "browser\_action" context type.

Syntax
------


```js
browser.browserAction.onClicked.addListener(listener)
browser.browserAction.onClicked.removeListener(listener)
browser.browserAction.onClicked.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`tab`

`tabs.Tab`. The tab that was active when the icon was clicked.

`OnClickData`

An object containing information about the click.

`modifiers`

An `array`. The keyboard modifiers active at the time of the click, being one or more of `Shift`, `Alt`, `Command`, `Ctrl`, or `MacCtrl`.

`button`

An `integer`. Indicates the button used to click the page action icon: `0` for a left-click or a click not associated with a mouse, such as one from the keyboard and `1` for a middle button or wheel click. Note that the right-click is not supported because Firefox consumes that click to display the context menu before this event is triggered.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

When the user clicks the icon, disable it for the active tab, and log the tab's URL:


```js
browser.browserAction.onClicked.addListener((tab) => {
  // disable the active tab
  browser.browserAction.disable(tab.id);
  // requires the "tabs" or "activeTab" permission, or host permissions for the URL
  console.log(tab.url);
});
```

### Example extensions

* bookmark-it
* favourite-colour
* find-across-tabs
* forget-it
* google-userinfo
* native-messaging
* open-my-page-button
* permissions
* runtime-examples
* store-collected-images

**Note:**

This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.openPopup()
=========================

Open the browser action's popup.

In stable versions of Firefox, you can only call this function from inside the handler for a user action. See Browser compatibility for details.

Syntax
------


```js
browser.browserAction.openPopup(
  options // optional object
)
```

### Parameters

`details` Optional

An object with the following properties:

`windowId` Optional

`integer`. Window to open the popup for. Defaults to the current window.


### Return value

A `Promise` that is resolved with no arguments.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Open the popup when the user selects a context menu item:


```js
browser.menus.create({
  id: "open-popup",
  title: "open popup",
  contexts: ["all"],
});

browser.menus.onClicked.addListener(() => {
  browser.browserAction.openPopup();
});
```
browserAction.ColorArray
========================

Type
----

An `array` of four integers in the range 0-255, defining an RGBA color. The four values specify the following channels:

1. Red
2. Green
3. Blue
4. Alpha (opacity).

For example, opaque red is `[255, 0, 0, 255]`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.setTitle()
========================

Sets the browser action's title. The title is displayed in a tooltip over the browser action's icon. You can pass a `tabId` in or a `windowId` as an optional parameter — if you do this then the title is changed only for the given tab or the given window. Tabs or windows without a specific title will inherit the global title text, which defaults to the `default_title` or `name` specified in the manifest.

Syntax
------


```js
browser.browserAction.setTitle(
  details // object
)
```

### Parameters

`details`

`object`. The new title and optionally the ID of the tab or window to target.

`title`

`string` or `null`. The string the browser action should display when moused over.

If `title` is an empty string, the used title will be the extension name, but `browserAction.getTitle` will still provide the empty string.

If `title` is `null`:

* If `tabId` is specified, and the tab has a tab-specific title set, then the tab will inherit the title from the window to which it belongs.
* if `windowId` is specified, and the window has a window-specific title set, then the window will inherit the global title.
* Otherwise, the global title will be reset to the manifest title.

`tabId` Optional

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

`windowId` Optional

`integer`. Sets the title for the given window.



* If `windowId` and `tabId` are both supplied, the function fails and the title is not set.
* If `windowId` and `tabId` are both omitted, the global title is set.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This code switches the title between "this" and "that" each time the user clicks the browser action:


```js
function toggleTitle(title) {
  if (title === "this") {
    browser.browserAction.setTitle({ title: "that" });
  } else {
    browser.browserAction.setTitle({ title: "this" });
  }
}

browser.browserAction.onClicked.addListener(() => {
  let gettingTitle = browser.browserAction.getTitle({});
  gettingTitle.then(toggleTitle);
});
```

### Example extensions

* bookmark-it

**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.getBadgeTextColor()
=================================

Gets the text color for the browser action's badge.

From Firefox 63, unless the badge text color is explicitly set using `browserAction.setBadgeTextColor()`, then the badge text color will be automatically set to black or white so as to maximize contrast with the specified badge background color. For example, if you set the badge background color to white, the default badge text color will be set to black, and vice versa.

Other browsers always use a white text color.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
browser.browserAction.getBadgeTextColor(
  details // object
)
```

### Parameters

`details`

`object`.

`tabId` Optional

`integer`. Specifies the tab to get the badge text color from.

`windowId` Optional

`integer`. Specifies the window from which to get the badge text color.



* If `windowId` and `tabId` are both supplied, the function fails.
* If `windowId` and `tabId` are both omitted, the global badge text color is returned.
### Return value

A `Promise` that will be fulfilled with the retrieved color as a `browserAction.ColorArray`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the badge's text color:


```js
function onGot(color) {
  console.log(color);
}

function onFailure(error) {
  console.log(error);
}

browser.browserAction.getBadgeTextColor({}).then(onGot, onFailure);
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.getBadgeText()
============================

Gets the browser action's badge text.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingText = browser.browserAction.getBadgeText(
  details               // object
)
```

### Parameters

`details`

An object with the following properties:

`tabId` Optional

`integer`. Specifies the tab from which to get the badge text.

`windowId` Optional

`integer`. Specifies the window from which to get the badge text.



* If windowId and tabId are both supplied, the function fails.
* If windowId and tabId are both omitted, the global badge text is returned.
### Return value

A `Promise` that will be fulfilled with a string containing the badge text.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the badge text:


```js
function gotBadgeText(text) {
  console.log(text);
}

let gettingBadgeText = browser.browserAction.getBadgeText({});
gettingBadgeText.then(gotBadgeText);
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.setBadgeBackgroundColor()
=======================================

Sets the background color for the badge. Tabs without a specific badge background color will inherit the global badge background color, which defaults to `[217, 0, 0, 255]` in Firefox.

From Firefox 63, unless the badge text color is explicitly set using `browserAction.setBadgeTextColor()`, then the badge text color will be automatically set to black or white so as to maximize contrast with the specified badge background color. For example, if you set the badge background color to white, the default badge text color will be set to black, and vice versa.

Other browsers always use a white text color, so setting a dark background may be preferable to ensure the text is readable.

Syntax
------


```js
browser.browserAction.setBadgeBackgroundColor(
  details // object
)
```

### Parameters

`details`

An object with the following properties:

`color`

The color, specified as one of:

* a string: any CSS <color> value, for example `"red"`, `"#FF0000"`, or `"rgb(255 0 0)"`. If the string is not a valid color, the returned promise will be rejected and the background color won't be altered.
* a ``browserAction.ColorArray`` object.
* `null`. If a `tabId` is specified, it removes the tab-specific badge background color so that the tab inherits the global badge background color. Otherwise it reverts the global badge background color to the default value.

`tabId` Optional

`integer`. Sets the badge background color only for the given tab. The color is reset when the user navigates this tab to a new page.

`windowId` Optional

`integer`. Sets the badge background color only for the given tab.



* If `windowId` and `tabId` are both supplied, the function fails and the color is not set.
* If `windowId` and `tabId` are both omitted, the global badge background color is set instead.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

The default color in Firefox is: `[217, 0, 0, 255]`.

Examples
--------

A background color that starts off as red, and turns green when the browser action is clicked:


```js
browser.browserAction.setBadgeText({ text: "1234" });
browser.browserAction.setBadgeBackgroundColor({ color: "red" });

browser.browserAction.onClicked.addListener(() => {
  browser.browserAction.setBadgeBackgroundColor({ color: "green" });
});
```


Set the badge background color only for the active tab:


```js
browser.browserAction.setBadgeText({ text: "1234" });
browser.browserAction.setBadgeBackgroundColor({ color: "red" });

browser.browserAction.onClicked.addListener((tab) => {
  browser.browserAction.setBadgeBackgroundColor({
    color: "green",
    tabId: tab.id,
  });
});
```

### Example extensions

* tabs-tabs-tabs

**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.setBadgeText()
============================

Sets the badge text for the browser action. The badge is displayed on top of the icon.

Tabs without a specific badge text will inherit the global badge text, which is `""` by default.

Syntax
------


```js
browser.browserAction.setBadgeText(
  details // object
)
```


This API is also available as `chrome.browserAction.setBadgeText()`.

### Parameters

`details`

An object with the following properties:

`text`

`string` or `null`. Any number of characters can be passed, but only about four can fit in the space.

Use an empty string - `""` - if you don't want any badge.

If a `tabId` is specified, `null` removes the tab-specific badge text so that the tab inherits the global badge text. Otherwise it reverts the global badge text to `""`.

If a `windowId` is specified, `null` removes the window-specific badge text so that the tab inherits the global badge text. Otherwise it reverts the global badge text to `""`.

`tabId` Optional

`integer`. Set the badge text only for the given tab. The text is reset when the user navigates this tab to a new page.

`windowId` Optional

`integer`. Set the badge text for the given window.



* If `windowId` and `tabId` are both supplied, the function fails.
* If `windowId` and `tabId` are both omitted, the global badge is set.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Add a badge indicating how many times the user clicked the button:


```js
let clicks = 0;

function increment() {
  browser.browserAction.setBadgeText({ text: (++clicks).toString() });
}

browser.browserAction.onClicked.addListener(increment);
```

### Example extensions

* tabs-tabs-tabs

**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.getBadgeBackgroundColor()
=======================================

Gets the background color of the browser action's badge.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
browser.browserAction.getBadgeBackgroundColor(
  details // object
)
```

### Parameters

`details`

An object with the following properties:

`tabId` Optional

`integer`. Specifies the tab to get the badge background color from.

`windowId` Optional

`integer`. Specifies the window from which to get the badge background color.



* If `windowId` and `tabId` are both supplied, the function fails.
* If `windowId` and `tabId` are both omitted, the global badge background color is returned.
### Return value

A `Promise` that will be fulfilled with the retrieved color as a `browserAction.ColorArray`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the badge's background color:


```js
function onGot(color) {
  console.log(color);
}

function onFailure(error) {
  console.log(error);
}

browser.browserAction.getBadgeBackgroundColor({}).then(onGot, onFailure);
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.enable()
======================

Enables the browser action for a tab. By default, browser actions are enabled for all tabs.

Syntax
------


```js
browser.browserAction.enable(
  tabId // optional integer
)
```

### Parameters

`tabId` Optional

`integer`. The id of the tab for which you want to enable the browser action.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Disable the browser action when clicked, and re-enable it every time a new tab is opened:


```js
browser.tabs.onCreated.addListener(() => {
  browser.browserAction.enable();
});

browser.browserAction.onClicked.addListener(() => {
  browser.browserAction.disable();
});
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.getPopup()
========================

Gets the HTML document set as the popup for this browser action.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingPopup = browser.browserAction.getPopup(
  details               // object
)
```

### Parameters

`details`

An object with the following properties:

`tabId` Optional

`integer`. The tab whose popup to get.

`windowId` Optional

`integer`. The windows whose popup to get.



* If `windowId` and `tabId` are both supplied, the function fails.
* If `windowId` and `tabId` are both omitted, the global popup is returned.
### Return value

A `Promise` that will be fulfilled with a string containing the URL for the popup's document. This will be a fully qualified URL, such as `moz-extension://d1d8a2eb-fe60-f646-af30-a866c5b39942/popups/popup2.html`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Get the popup's URL:


```js
function gotPopup(popupURL) {
  console.log(popupURL);
}

let gettingPopup = browser.browserAction.getPopup({});
gettingPopup.then(gotPopup);
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.
browserAction.isEnabled()
=========================

Returns `true` if the browser action is enabled.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingIsEnabled = browser.browserAction.isEnabled(
  details // object
)
```

### Parameters

`details`

`object`. An object optionally containing the `tabId` or `windowId` to check.

`tabId` Optional

`integer`. ID of a tab to check.

`windowId` Optional

`integer`. ID of a window to check.



* If windowId and tabId are both supplied, the function fails.
* If windowId and tabId are both omitted, the global enabled/disabled status is returned.
### Return value

A `Promise` that will be fulfilled with `true` if the extension's browser action is enabled, and `false` otherwise.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Check the global state:


```js
browser.browserAction.isEnabled({}).then((result) => {
  console.log(result);
});
```


Check the state of the currently active tab:


```js
async function enabledInActiveTab() {
  let tabs = await browser.tabs.query({
    currentWindow: true,
    active: true,
  });
  let enabled = await browser.browserAction.isEnabled({
    tabId: tabs[0].id,
  });
  console.log(enabled);
}
```
browserAction.disable()
=======================

Disables the browser action for a tab, meaning that it cannot be clicked when that tab is active.

Syntax
------


```js
browser.browserAction.disable(
  tabId // optional integer
)
```

### Parameters

`tabId` Optional

`integer`. The id of the tab for which you want to disable the browser action.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Disable the browser action when clicked, and re-enable it every time a new tab is opened:


```js
browser.tabs.onCreated.addListener(() => {
  browser.browserAction.enable();
});

browser.browserAction.onClicked.addListener(() => {
  browser.browserAction.disable();
});
```


Disable the browser action only for the active tab:


```js
browser.browserAction.onClicked.addListener((tab) => {
  browser.browserAction.disable(tab.id);
});
```


**Note:** This API is based on Chromium's `chrome.browserAction` API. This documentation is derived from `browser_action.json` in the Chromium code.