recursal/MDN huggingface dataset:
tabs.onAttached
===============

Fired when a tab is attached to a window, for example because it was moved between windows.

Syntax
------


```js
browser.tabs.onAttached.addListener(listener)
browser.tabs.onAttached.removeListener(listener)
browser.tabs.onAttached.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`. ID of the tab that was attached to a new window.

`attachInfo`

`object`. ID of the new window, and index of the tab within it. See the attachInfo section for more details.


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

### attachInfo

`newWindowId`

`integer`. ID of the new window.

`newPosition`

`integer`. Index position that the tab has in the new window.

Examples
--------

Listen for attach events, and log the info:


```js
function handleAttached(tabId, attachInfo) {
  console.log(`Tab: ${tabId} attached`);
  console.log(`New window: ${attachInfo.newWindowId}`);
  console.log(`New index: ${attachInfo.newPosition}`);
}

browser.tabs.onAttached.addListener(handleAttached);
```

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.getSelected()
==================

**Warning:** This method has been deprecated. Use `tabs.query({active: true})` instead.

Gets the tab that is selected in the specified window.

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

Syntax
------


```js
let gettingSelected = browser.tabs.getSelected(
  windowId           // optional integer
)
```

### Parameters

`windowId` Optional

`integer`. Defaults to the current window.

### Return value

A `Promise` that will be fulfilled with a `tabs.Tab` object containing information about the selected tab. If the tab 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.onCreated
==============

Fired when a tab is created.

Note that the tab's URL may not be given its final value at the time this event fired. In particular, Firefox opens a new tab with the URL "about:blank" before loading the new page into it. You can listen to `tabs.onUpdated` events to be notified when a URL is set.

Syntax
------


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

`tab`

`tabs.Tab`. Details of the tab that was created.


Examples
--------

Log the IDs of newly created tabs:


```js
function handleCreated(tab) {
  console.log(tab.id);
}

browser.tabs.onCreated.addListener(handleCreated);
```

### Example extensions

* session-state
* 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.onHighlighted
==================

Fired when the set of highlighted tabs in a window changes.

Note that before version 63, Firefox didn't have the concept of highlighting multiple tabs, so this event was just an alias for `tabs.onActivated`.

Syntax
------


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

`highlightInfo`

`object`. ID(s) of the highlighted tabs, and ID of their window. See the highlightInfo section for more details.


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

### highlightInfo

`windowId`

`integer`. ID of the window whose tabs changed.

`tabIds`

`array` of `integer`. IDs of the highlighted tabs in the window.

Examples
--------

Listen for highlighting events, and log the IDs of highlighted tabs:


```js
function handleHighlighted(highlightInfo) {
  console.log(`Highlighted tabs: ${highlightInfo.tabIds}`);
}

browser.tabs.onHighlighted.addListener(handleHighlighted);
```

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.onReplaced
===============

Fired when a tab is replaced with another tab due to prerendering or instant.

This event may not be relevant for or supported by browsers other than Chrome.

Syntax
------


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

`addedTabId`

`integer`. ID of the replacement tab.

`removedTabId`

`integer`. ID of the tab that was replaced.


Examples
--------

Listen for replacement events, and log the associated info:


```js
function handleReplaced(addedTabId, removedTabId) {
  console.log(`New tab: ${addedTabId}`);
  console.log(`Old tab: ${removedTabId}`);
}

browser.tabs.onReplaced.addListener(handleReplaced);
```

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.show()
===========

Shows one or more tabs that were previously hidden by a call to `tabs.hide`.

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

Syntax
------


```js
let showing = browser.tabs.show(
  tabIds          // integer or integer array
)
```

### Parameters

`tabIds`

`integer` or `array` of `integer`. The IDs of the tab or tabs to show.

### Return value

A `Promise` that will be fulfilled with no arguments. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Show a single tab:


```js
function onShown() {
  console.log(`Shown`);
}

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

browser.tabs.show(2).then(onShown, onError);
```


Show multiple tabs:


```js
function onShown() {
  console.log(`Shown`);
}

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

browser.tabs.show([15, 14, 1]).then(onShown, onError);
```

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

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

Saves the current page as a PDF file. This will open a dialog, supplied by the underlying operating system, asking the user where they want to save the PDF file.

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

Syntax
------


```js
let saving = browser.tabs.saveAsPDF(
  pageSettings   // object
)
```

### Parameters

`pageSettings`

`object`. Settings for the saved page, as a `tabs.PageSettings` object. This object must be given, but all its properties are optional. Any properties not specified here will get the default values listed in the `PageSettings` documentation.

### Return value

A `Promise` that will be fulfilled with a status string when the dialog has closed. The string may be any of:

* "saved"
* "replaced"
* "canceled"
* "not\_saved"
* "not\_replaced"
Examples
--------

In this example a background script listens for a click on a browser action, then tries to save the currently active tab as a PDF file, then logs the result:


```js
browser.browserAction.onClicked.addListener(() => {
  browser.tabs.saveAsPDF({}).then((status) => {
    console.log(status);
  });
});
```

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

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

Hides one or more tabs.

Hidden tabs are no longer visible in the browser's tabstrip. Hidden tabs are not automatically discarded: the code running in them continues to run. You can explicitly discard tabs whenever you hide them: although this is not appropriate in all situations, it will help to reduce the resources used by the browser.

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

Not all tabs are eligible for being hidden:

* Tabs that are pinned cannot be hidden.
* Tabs that are sharing the screen, microphone or camera cannot be hidden.
* The current active tab cannot be hidden.
* Tabs that are in the process of being closed cannot be hidden.

The first time an extension hides a tab, the browser will tell the user that the tab is being hidden, show them how they can access the hidden tab, and give them the option of disabling the extension instead.

To use this API you must have the "tabHide" permission.

Syntax
------


```js
let hiding = browser.tabs.hide(
  tabIds          // integer or integer array
)
```

### Parameters

`tabIds`

`integer` or `array` of `integer`. The IDs of the tab or tabs to hide.

If any of these tabs are not eligible for being hidden, they will not be hidden, but the call will still succeed and eligible tabs will still be hidden. For example, if you pass `[1, 3]`, and `1` identifies the active tab, then only `3` will be hidden.

However, if any of the tab IDs are invalid, the call will fail and no tabs will be hidden.

### Return value

A `Promise` that will be fulfilled with an array containing the IDs of the tabs that were hidden. If any error occurs, the promise will be rejected with an error message.

Examples
--------

Hide a single tab:


```js
function onHidden() {
  console.log(`Hidden`);
}

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

browser.tabs.hide(2).then(onHidden, onError);
```


Hide multiple tabs:


```js
function onHidden() {
  console.log(`Hidden`);
}

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

browser.tabs.hide([15, 14, 1]).then(onHidden, onError);
```

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

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

Specifies the reason a tab was muted or unmuted.

Type
----

Values of this type are strings. Possible values are:

"capture"

Tab capture started, forcing a muted state change.

"extension"

An extension set the muted state. If this is the reason, `extensionId` in `tabs.mutedInfo` will contain the ID of the extension responsible.

"user"

The user set the muted state.

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.toggleReaderMode()
=======================

Toggles Reader Mode for the given tab.

This function toggles Reader Mode for the given tab. It takes a tab ID as a parameter: if this is omitted, the currently active tab is toggled.

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

Reader Mode, also known as Reader View, is a browser feature that makes it easier for the user to focus on an article by:

* hiding non-essential page elements like sidebars, footers, and ads
* changing the page's text size, contrast and layout for better readability.

Reader Mode is useful specifically for articles: meaning, pages that have a body of text content as their main feature. Pages that don't have an identifiable article are not eligible for display in Reader Mode. To find out whether a page is an article, check the `isArticle` property of `tabs.Tab`.

To find out whether a tab is already in Reader Mode, check the `isInReaderMode` property of `tabs.Tab`. To track tabs changing into or out of Reader Mode, you'll need to keep track of the current state of all tabs, and check when `isInReaderMode` changes:


```js
function handleUpdated(tabId, changeInfo, tabInfo) {
  if (changeInfo.status === "complete") {
    console.log(`Tab ${tabId} reader mode: ${tabInfo.isInReaderMode}`);
  }
}

browser.tabs.onUpdated.addListener(handleUpdated);
```

Syntax
------


```js
let toggling = browser.tabs.toggleReaderMode(
  tabId            // optional integer
)
```

### Parameters

`tabId` Optional

`integer`. The ID of the tab to display in Reader Mode. Defaults to the selected tab of the current window.

### Return value

A `Promise` that will be fulfilled with no arguments when the tab has been updated. If any error occurs (for example, because the page was not an article), the promise will be rejected with an error message.

Examples
--------

This code switches every new page into Reader Mode, if that page is eligible for it:


```js
function switchToReaderMode(tabId, changeInfo, tabInfo) {
  if (changeInfo.isArticle) {
    browser.tabs.toggleReaderMode(tabId);
  }
}

browser.tabs.onUpdated.addListener(switchToReaderMode);
```

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

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

Defines whether zoom changes will persist for the page's origin, or only take effect in this tab. This defaults to `per-origin` when `tabs.zoomSettingsMode` is "automatic", and is always `per-tab` otherwise.

Type
----

Values of this type are strings. Possible values are:

"per-origin"

All other tabs with the same origin as this tab will have the zoom changes applied to them. This scope is only available if `tabs.zoomSettingsMode` is "automatic".

"per-tab"

Zoom changes only take effect in this tab, and zoom changes in other tabs will not affect the zooming of this tab. Also:

* in Firefox the zoom level persists across page loads and navigation within the tab.
* in Chrome-based browsers zoom changes are reset on navigation; navigating a tab will always load pages with their per-origin zoom factors.

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.MutedInfo
==============

This object contains a boolean indicating whether the tab is muted, and the reason for the last state change.

Type
----

Values of this type are objects. They contain the following properties:

`extensionId` Optional

`string`. The ID of the extension that last changed the muted state. Not set if an extension was not the reason the muted state last changed.

`muted`

`boolean`. Whether the tab is currently muted. Equivalent to whether the muted audio indicator is showing.

`reason` Optional

`tabs.MutedInfoReason`. The reason the tab was muted or unmuted. Not set if the tab's muted state has never been changed.

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.goBack()
=============

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

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

Syntax
------


```js
let withGoingBack = browser.tabs.goBack(
  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 back to the previous page in the current tab:


```js
function onGoBack() {
  console.log("Gone back");
}

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

let goingBack = browser.tabs.goBack();
goingBack.then(onGoBack, onError);
```


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

Creates a data URL encoding the image of an area of the given tab. You must have the `<all_urls>` permission to use this method.

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

Syntax
------


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

### Parameters

`tabId` Optional

`integer`. ID of the tab to capture. Defaults to the active tab in 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.captureTab();
  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.getAllInWindow()
=====================

**Warning:** This method has been deprecated. Use `tabs.query({currentWindow: true})` instead.

Gets details about all tabs in the specified window.

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

Syntax
------


```js
let getting = browser.tabs.getAllInWindow(
  windowId            // optional integer
)
```

### Parameters

`windowId` Optional

`integer`. Defaults to the current window.

### Return value

A `Promise` that will be fulfilled with an `array` of ``tabs.Tab`` objects, containing information about all the tabs in the window. 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.get()
==========

Given a tab ID, get the tab's details as a `tabs.Tab` object.

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

Syntax
------


```js
let getting = browser.tabs.get(
  tabId              // integer
)
```

### Parameters

`tabId`

`integer`. ID of the tab to get.

### Return value

A `Promise` that will be fulfilled with a `tabs.Tab` object containing information about the tab. If the tab could not be found or some other error occurs, the promise will be rejected with an error message.

Examples
--------

Get information about a tab when it is activated:


```js
async function logListener(info) {
  try {
    let tabInfo = await browser.tabs.get(info.tabId);
    console.log(tabInfo);
  } catch (error) {
    console.error(error);
  }
}

browser.tabs.onActivated.addListener(logListener);
```

### Example extensions

* chill-out
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.discard()
==============

Discards one or more tabs.

Some browsers automatically "discard" unused tabs to free memory. Discarded tabs stay visible in the tabstrip. The browser remembers the tab's state and restores it when the user selects the tab. The details of when tabs are and what is discarded are browser-specific.

You can control whether the browser or this API discards a tab by setting its `autoDiscardable` property to `false` in `tabs.update`. This setting prevents the browser from discarding the tab. The tab can then only be discarded with this API.

It's not possible to discard the active tab or a tab whose document contains a `beforeunload` listener that would display a prompt.

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

Syntax
------


```js
let discarding = browser.tabs.discard(
  tabIds          // integer or integer array
)
```

### Parameters

`tabIds`

`integer` or `array` of `integer`. The IDs of the tab or tabs to discard.

### Return value

A `Promise` that will be fulfilled with no arguments when all the specified tabs have been discarded. If any error occurs (for example, invalid tab IDs), the promise will be rejected with an error message.

If the ID of the active tab is passed in, it will not be discarded, but the promise will be fulfilled and any other tabs passed in will be discarded.

Examples
--------

Discard a single tab:


```js
function onDiscarded() {
  console.log(`Discarded`);
}

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

let discarding = browser.tabs.discard(2);
discarding.then(onDiscarded, onError);
```


Discard multiple tabs:


```js
function onDiscarded() {
  console.log(`Discarded`);
}

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

let discarding = browser.tabs.discard([15, 14, 1]);
discarding.then(onDiscarded, 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.