recursal/MDN huggingface dataset:
action.getTitle()
=================

Gets the browser action's title.

**Note:** This API is available in Manifest V3 or higher.

Just as you can set the title on a per-tab basis using `action.setTitle()`, so you can retrieve a tab-specific title by passing the tab's ID into this function.

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

Syntax
------


```js
let gettingTitle = browser.action.getTitle(
  details               // object
)
```

### Parameters

`details`

An object with the following properties:

`tabId` Optional

`integer`. Specify the tab to get the title from.

`windowId` Optional

`integer`. Specify the window to get the title from.



* If `windowId` and `tabId` are both supplied, the function fails and the promise it returns is rejected.
* If `windowId` and `tabId` are both omitted, the global title is returned.
### Return value

A `Promise` that will be fulfilled with a string containing the browser action's title.

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.action.setTitle({ title: "that" });
  } else {
    browser.action.setTitle({ title: "this" });
  }
}

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.getBadgeTextColor()
==========================

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

**Note:** This API is available in Manifest V3 or higher.

In Firefox, unless the badge text color is explicitly set using `action.setBadgeTextColor()`, the badge text color is 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 is 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.action.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 `action.ColorArray`.

Examples
--------

Log the badge's text color:


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

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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.isEnabled()
==================

Returns `true` if the browser action is enabled.

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


```js
let gettingIsEnabled = browser.action.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.

Examples
--------

Check the global state:


```js
browser.action.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.action.isEnabled({
    tabId: tabs[0].id,
  });
  console.log(enabled);
}
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
action.getBadgeText()
=====================

Gets the browser action's badge text.

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


```js
let gettingText = browser.action.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.

Examples
--------

Log the badge text:


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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.getPopup()
=================

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

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


```js
let gettingPopup = browser.action.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`.

Examples
--------

Get the popup's URL:


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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.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.

**Note:** This API is available in Manifest V3 or higher.

In Firefox, unless the badge text color is explicitly set using `action.setBadgeTextColor()`, then the badge text color iw automatically set to black or white 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 is 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.action.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 ``action.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.
Examples
--------

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


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

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


Set the badge background color only for the active tab:


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

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

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]`.

**Note:** This API is based on Chromium's `chrome.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.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 specified tab or window. Tabs or windows without a specific title inherit the global title text, which defaults to the `default_title` or `name` specified in the manifest.

**Note:** This API is available in Manifest V3 or higher.

Syntax
------


```js
browser.action.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 `action.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.
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.action.setTitle({ title: "that" });
  } else {
    browser.action.setTitle({ title: "this" });
  }
}

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.setBadgeText()
=====================

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

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


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


This API is also available as `chrome.action.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.
Examples
--------

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


```js
let clicks = 0;

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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.getBadgeBackgroundColor()
================================

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

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


```js
browser.action.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 `action.ColorArray`.

Examples
--------

Log the badge's background color:


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

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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.setBadgeTextColor()
==========================

Sets the text color for the browser action's badge. Tabs without a specific badge text color will inherit the global badge text color.

**Note:** This API is available in Manifest V3 or higher.

Syntax
------


```js
browser.action.setBadgeTextColor(
  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 text color won't be altered.
* a ``action.ColorArray`` object.
* `null`. If a `tabId` is specified, it removes the tab-specific badge text color so that the tab inherits the global badge text color. Otherwise it reverts the global badge text color to the default value.

`tabId` Optional

`integer`. Sets the badge text 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 text 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 text color is set instead.
Examples
--------

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


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

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


Set the badge text color only for the active tab:


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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.ImageDataType
====================

Pixel data for an image. Must be an `ImageData` object (for example, from a `<canvas>` element).

Type
----

An `ImageData` object.

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.getUserSettings()
========================

Gets the user-specified settings for the browser action.

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


```js
let userSettings = await browser.action.getUserSettings();
```

### Parameters

This function takes no parameters.

### Return value

A `Promise` that fulfills with an object with these properties:

`userSettings`

An object containing the user-specified settings for the browser action with these properties:

`isOnToolbar` Optional

`boolean`. Whether the user has pinned the action's icon to the browser UI. This setting does not indicate whether the action icon is visible. The icon's visibility depends on the size of the browser window and the layout of the browser UI.


Examples
--------

This code logs a message indicating whether the action is pinned or not:


```js
function gotSettings(userSettings) {
  if (userSettings.isOnToolbar) {
    console.log("Action is pinned to toolbar.");
  } else {
    console.log("Action is not pinned to toolbar.");
  }
}

let gettingUserSettings = browser.action.getUserSettings();
gettingUserSettings.then(gotSettings);
```

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.action` API.
action.openPopup()
==================

Open the browser action's popup.

**Note:** This API is available in Manifest V3 or higher.

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

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.action.openPopup();
});
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
action.enable()
===============

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

**Note:** This API is available in Manifest V3 or higher.

Syntax
------


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

### Parameters

`tabId` Optional

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

Examples
--------

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


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

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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
action.onClicked
================

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

**Note:** This API is available in Manifest V3 or higher.

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

Syntax
------


```js
browser.action.onClicked.addListener(listener)
browser.action.onClicked.removeListener(listener)
browser.action.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.


Examples
--------

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


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

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.action` API. This documentation is derived from `browser_action.json` in the Chromium code.