recursal/MDN huggingface dataset:
tabs.warmup()
=============

To optimize system resource usage, browsers may drop GPU resources associated with tabs that the user has not accessed for a certain amount of time. If a browser has done this for a tab, then reactivating the tab (for example, when the user switches to it) may take longer than it normally would.

The `tabs.warmup()` API enables an extension to start the process of rendering the resources for an inactive tab, if the extension expects that the user might switch to the tab soon. This then makes the actual tab switch faster than it would be otherwise.

Note this API does not work on discarded tabs and does not need to be called immediately prior to switching tabs. It is merely a performance improvement when the tab switch can be anticipated, such as when hovering over a button that when clicked would switch to the tab.

It is expected that this API would mostly be useful to tab management extensions.

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

Syntax
------


```js
let warming = browser.tabs.warmup(
  tabId               // integer
)
```

### Parameters

`tabId`

`integer`. ID of the tab to warm up. If the argument passed here is not an integer (in particular, if it is `null` or `undefined`) then `warmup()` will throw an exception synchronously.

### Return value

A `Promise` that will be fulfilled with no arguments if the tab identified by `tabId` is successfully warmed up. If `tabId` does not identify an open tab, or if warming up fails for some other reason, then the promise will be rejected with an error message.

Examples
--------

This code adds a listener to the `browserAction.onClicked` event. The listener retrieves all tabs in the current window that contain pages under "https://developer.mozilla.org/" and warms up the first one that it finds.


```js
function onSuccess() {
  console.log("success!");
}

function onFailure(error) {
  // e.g. ID of a nonexistent tab
  console.error(error);
}

async function warmupMDN() {
  const mdnTabs = await browser.tabs.query({
    currentWindow: true,
    url: "https://developer.mozilla.org/\*",
  });

  if (mdnTabs.length > 0) {
    const warming = browser.tabs.warmup(mdnTabs[0].id);
    warming.then(onSuccess, onFailure);
  }
}

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

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

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

Highlights (selects) one or more tabs. Tabs are specified using a window ID and a range of tab indices.

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

Syntax
------


```js
let highlighting = browser.tabs.highlight(
  highlightInfo         // object
)
```

### Parameters

`highlightInfo`

`object`.

`windowId` Optional

`integer`. ID of the window that contains the tabs.

`populate` Optional

`boolean`. Defaults to `true`. If set to `false`, the `windows.Window` object won't have a `tabs` property containing a list of `tabs.Tab` objects representing the tabs open in the window.

**Note:** Populating the window (the default behavior) can be an expensive operation if there are lots of tabs. For better performance it's recommended to manually set `populate` to `false` if you don't need tab details.

`tabs`

`array` of integer values specifying one or more tab indices to highlight. Previously highlighted tabs not included in `tabs` will stop being highlighted. The first tab in `tabs` will become active.


### Return value

A `Promise` that will be fulfilled with a `windows.Window` object containing details about the window whose tabs were highlighted. If the window could not be found or some other error occurs, the promise will be rejected with an error message.

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

Gets the current zoom factor for the specified tab.

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

Syntax
------


```js
let gettingZoom = browser.tabs.getZoom(
  tabId                     // optional integer
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to get the current zoom factor from. Defaults to the active tab of the current window.

### Return value

A `Promise` that will be fulfilled with the tab's current zoom factor, as a number between 0.3 and 5. If the tab could not be found or some other error occurs, the promise will be rejected with an error message.

Examples
--------

Get the zoom factor for the current tab:


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

function onError(error) {
  console.log(`Error: ${error}`);
}

let gettingZoom = browser.tabs.getZoom();
gettingZoom.then(onGot, onError);
```


Get the zoom factor for the tab whose ID is 2:


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

function onError(error) {
  console.log(`Error: ${error}`);
}

let gettingZoom = browser.tabs.getZoom(2);
gettingZoom.then(onGot, onError);
```

### Example extensions

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

Removes from a page CSS which was previously injected by a call to `tabs.insertCSS()`.

**Note:** When using Manifest V3 or higher, use `scripting.insertCSS()` and `scripting.removeCSS()` to insert and remove CSS.

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

Syntax
------


```js
let removing = browser.tabs.removeCSS(
  tabId,           // optional integer
  details          // object
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab from which to remove the CSS. Defaults to the active tab of the current window.

`details`

An object describing the CSS to remove from the page. It contains the following properties:

`allFrames` Optional

`boolean`. If `true`, the code will be removed from all frames of the current page. If it is `false`, code is only removed from the top frame. Defaults to `false`.

`code` Optional

`string`. CSS to remove, as a text string. This must exactly match a CSS string previously inserted into the page using `tabs.insertCSS()`.

`cssOrigin` Optional

`string`. This can take one of two values: "user", for CSS added as a user stylesheet, or "author" for CSS added as an author stylesheet. If this option was set previously by `tabs.insertCSS()`, then it must exactly match.

`file` Optional

`string`. Path to a file containing the CSS to remove. This must exactly match a CSS file previously inserted into the page using `tabs.insertCSS()`.

`frameId` Optional

`integer`. The frame from which to remove the CSS. Defaults to `0` (the top-level frame).

`matchAboutBlank` Optional

`boolean`. If `true`, the CSS will be removed from embedded "about:blank" and "about:srcdoc" frames if your extension has access to their parent document. Defaults to `false`.


### Return value

A `Promise` that will be fulfilled with no arguments when all the CSS has been removed. If any error occurs, the promise will be rejected with an error message.

Examples
--------

This example adds some CSS using `tabs.insertCSS`, then removes it again when the user clicks a browser action:


```js
let css = "body { border: 20px dotted pink; }";

function onError(error) {
  console.log(`Error: ${error}`);
}

let insertingCSS = browser.tabs.insertCSS(2, { code: css });
insertingCSS.then(null, onError);

browser.browserAction.onClicked.addListener(() => {
  let removing = browser.tabs.removeCSS(2, { code: css });
  removing.then(null, onError);
});
```

### Example extensions

* apply-css
* beastify
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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.duplicate()
================

Duplicates a tab, given its ID.

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

Syntax
------


```js
let duplicating = browser.tabs.duplicate(
  tabId,              // integer
  duplicateProperties // optional object
)
```

### Parameters

`tabId`

`integer`. The ID of the tab to be duplicated.

`duplicateProperties` Optional

`object`. An object describing how the tab is duplicated. It contains the following properties:

`index` Optional

`integer`. The position of the new tab in the window. The value is constrained to the range zero to the number of tabs in the window.

`active` Optional

`boolean`. Whether the tab becomes the active tab in the window. Does not affect whether the window is focused. Defaults to `true`.


### Return value

A `Promise` that will be fulfilled with a `tabs.Tab` object containing details about the duplicated tab. The `Tab` object only contains `url`, `title` and `favIconUrl` if the extension has the `"tabs"` permission or matching host permissions. If any error occurs the promise will be rejected with an error message.

**Note:** Beginning with Firefox 68, the promise returned by browser.tabs.duplicate() resolves as soon as the tab has been duplicated. Previously, the promise only resolved once the tab had fully been loaded.

Examples
--------

Duplicate the first tab, and then log the ID of the newly created tab:


```js
function onDuplicated(tabInfo) {
  console.log(tabInfo.id);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

// Duplicate the first tab in the array
function duplicateFirstTab(tabs) {
  console.log(tabs);
  if (tabs.length > 0) {
    let duplicating = browser.tabs.duplicate(tabs[0].id);
    duplicating.then(onDuplicated, onError);
  }
}

// Query for all open tabs
let querying = browser.tabs.query({});
querying.then(duplicateFirstTab, onError);
```

### Example extensions

* tabs-tabs-tabs
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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.onActiveChanged
====================

**Warning:** This event is deprecated. Use `tabs.onActivated` instead.

Fires when the selected tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to `tabs.onUpdated` events to be notified when a URL is set.

Syntax
------


```js
browser.tabs.onActiveChanged.addListener(listener)
browser.tabs.onActiveChanged.removeListener(listener)
browser.tabs.onActiveChanged.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:

`tabId`

`integer`. The ID of the tab that has become active.

`selectInfo`

`object`. See the selectInfo section for more details.


Additional objects
------------------

### selectInfo

`windowId`

`integer`. The ID of the window containing the selected tab.

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

Creates a data URL encoding the image of an area of the currently active tab in the specified window. You must have the `<all_urls>` permission to use this method. (Alternately, Chrome allows use of this method with the `activeTab` permission and a qualifying user gesture).

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

Syntax
------


```js
let capturing = browser.tabs.captureVisibleTab(
  windowId,               // optional integer
  options                 // optional extensionTypes.ImageDetails
)
```

### Parameters

`windowId` Optional

`integer`. The target window. Defaults to the current window.

`options` Optional

`extensionTypes.ImageDetails`.

### Return value

A `Promise` that will be fulfilled with a data URL which encodes the captured image. May be assigned to the 'src' property of an HTML Image element for display. If any error occurs the promise will be rejected with an error message.

Examples
--------

Capture an image of the active tab in the current window, with default settings:


```js
function onCaptured(imageUri) {
  console.log(imageUri);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener(() => {
  let capturing = browser.tabs.captureVisibleTab();
  capturing.then(onCaptured, onError);
});
```

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

Navigate to the next page in tab's history, if available.

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

Syntax
------


```js
let goingForward = browser.tabs.goForward(
  tabId,                       // optional integer
  callback                       // optional function
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to navigate. Defaults to the active tab of the current window.

`callback` Optional

`function`. When the page navigation finishes, this function is called without parameters.

### Return value

A `Promise` that is fulfilled when the page navigation finishes.

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

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

Examples
--------

Go forward to the next page in the current tab:


```js
function onGoForward() {
  console.log("Gone forward");
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let goingForward = browser.tabs.goForward();
goingForward.then(onGoForward, onError);
```


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

Opens print preview for the active tab.

This is an asynchronous function that returns a `Promise`. An extension can detect when print preview has been closed by listening to the afterprint event:


```js
window.addEventListener("afterprint", resumeFunction, false);
```

Syntax
------


```js
let openingPreview = browser.tabs.printPreview()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with no arguments when the preview page has opened.

Examples
--------

In this example a background script listens for a click on a browser action, then opens print preview for the currently active tab:


```js
browser.browserAction.onClicked.addListener(() => {
  browser.tabs.printPreview().then(() => {
    console.log("Entered print preview");
  });
});
```

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
tabs.TAB\_ID\_NONE
==================

A special ID value given to tabs that are not browser tabs (for example, tabs in devtools windows).

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

Closes one or more tabs.

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

Syntax
------


```js
let removing = browser.tabs.remove(
  tabIds          // integer or integer array
)
```

### Parameters

`tabIds`

`integer` or `array` of `integer` The ids of the tab or tabs to close.

### Return value

A `Promise` that will be fulfilled with no arguments when all the specified tabs have been removed or their `beforeunload` prompts have been handled. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Close a single tab:


```js
function onRemoved() {
  console.log(`Removed`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let removing = browser.tabs.remove(2);
removing.then(onRemoved, onError);
```


Close multiple tabs:


```js
function onRemoved() {
  console.log(`Removed`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let removing = browser.tabs.remove([15, 14, 1]);
removing.then(onRemoved, onError);
```

### Example extensions

* contextual-identities
* tabs-tabs-tabs
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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.TabStatus
==============

Indicates whether the tab has finished loading.

Type
----

Values of this type are strings. Possible values are: `"loading"` and `"complete"`.

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

Detects the primary language of the content in a tab, using the Compact Language Detector (CLD).

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

Syntax
------


```js
let detecting = browser.tabs.detectLanguage(
  tabId,                  // optional integer
  callback                // optional function
)
```

### Parameters

`tabId` Optional

`integer`. Defaults to the active tab of the current window.

`callback` Optional

`function`. Currently, if a `tabId` is specified, this method uses this callback to return the results instead of returning a promise. The callback receives as its only input parameter a string containing the detected language code such as `en` or `fr`.

### Return value

A `Promise` that will be fulfilled with a string representing an ISO language code such as `en` or `fr`. For a complete list of languages supported by this method, see kLanguageInfoTable. For an unknown language, `"und"` will be returned (but see bug 1288263). If any error occurs the promise will be rejected with an error message.

Examples
--------

Detect and log the language of the active tab when the user clicks a browser action:


```js
function onLanguageDetected(lang) {
  console.log(`Language is: ${lang}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.browserAction.onClicked.addListener(() => {
  browser.tabs.detectLanguage().then(onLanguageDetected, onError);
});
```


Detect and log the language of every open tab when the user clicks a browser action (note that this example requires the "tabs" permission):


```js
function onLanguageDetected(url, lang) {
  console.log(`Language in ${url} is: ${lang}`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

function detectLanguages(tabs) {
  for (const tab of tabs) {
    browser.tabs
      .detectLanguage(tab.id)
      .then((lang) => onLanguageDetected(tab.url, lang), onError);
  }
}

browser.browserAction.onClicked.addListener(() => {
  browser.tabs.query({}).then(detectLanguages, onError);
});
```

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

Sends a single message from the extension's background scripts (or other privileged scripts, such as popup scripts or options page scripts) to any content scripts or extension pages/iframes that belong to the extension and are running in the specified tab.

The message will be received in the extension context by any listeners to the `runtime.onMessage` event. Listeners may then optionally return something as a response back to the sender.

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

**Note:** You can also use a connection-based approach to exchange messages.

Syntax
------


```js
const sending = browser.tabs.sendMessage(
  tabId,     // integer
  message,   // any
  options    // optional object
)
```

### Parameters

`tabId`

`integer`. ID of the tab whose content scripts we want to send a message to.

`message`

`any`. An object that can be serialized (see Data cloning algorithm).

`options` Optional

`object`.

`frameId` Optional

`integer`. Sends the message to a specific frame identified by `frameId` instead of all frames in the tab. Whether the content script is executed in all frames depends on the `all_frames` setting in the `content_scripts` section of `manifest.json`.


### Return value

A `Promise` that will be fulfilled with the response object sent by the handler of the message in the content script, or with no arguments if the content script did not send a response.

If an error occurs while connecting to the specified tab or any other error occurs, the promise will be rejected with an error message.

If several frames respond to the message, the promise is resolved to one of answers.

Examples
--------

Here's an example of a background script that sends a message to the content scripts running in the active tab when the user clicks the browser action. The background script also expects the content script to send a response:


```js
// background-script.js
"use strict";

function onError(error) {
  console.error(`Error: ${error}`);
}

function sendMessageToTabs(tabs) {
  for (const tab of tabs) {
    browser.tabs
      .sendMessage(tab.id, { greeting: "Hi from background script" })
      .then((response) => {
        console.log("Message from the content script:");
        console.log(response.response);
      })
      .catch(onError);
  }
}

browser.browserAction.onClicked.addListener(() => {
  browser.tabs
    .query({
      currentWindow: true,
      active: true,
    })
    .then(sendMessageToTabs)
    .catch(onError);
});
```


Here's the corresponding content script:


```js
// content-script.js
"use strict";

browser.runtime.onMessage.addListener((request) => {
  console.log("Message from the background script:");
  console.log(request.greeting);
  return Promise.resolve({ response: "Hi from content script" });
});
```

### Example extensions

* beastify
* cookie-bg-picker
* imagify
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.tabs` API. This documentation is derived from `tabs.json` in the Chromium code.
tabs.print()
============

Call this function to print the contents of the active tab. If this function is called, the user will be presented with the print dialog from the underlying platform, and will have the chance to change the print settings and then print the currently active tab.

Syntax
------


```js
browser.tabs.print()
```

### Parameters

None.

### Return value

None.

Examples
--------

In this example a background script listens for a click on a browser action, then tries to print the currently active tab:


```js
browser.browserAction.onClicked.addListener(() => {
  browser.tabs.print();
});
```

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

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