tabs.query()
============

Gets all tabs that have the specified properties, or all tabs if no properties are specified.

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

Syntax
------


```js
let querying = browser.tabs.query(queryObj)
```

### Parameters

`queryObj`

`object`. The `query()` function will only get tabs whose properties match the properties included here.

See the `tabs.Tab` documentation to learn more about these properties.

`active` Optional

`boolean`. Whether the tabs are active in their windows.

`audible` Optional

`boolean`. Whether the tabs are audible.

`autoDiscardable` Optional

`boolean`. Whether the tab can be discarded by the browser. The default value is `true`. When set to `false`, the browser cannot automatically discard the tab. However, the tab can be discarded by `tabs.discard`.

`cookieStoreId` Optional

`string` or `array` of `string`. Use this to return tabs whose `tab.cookieStoreId` matches any of the `cookieStoreId` strings. This option is only available if the add-on has the `"cookies"` permission. See Work with contextual identities for more information.

`currentWindow` Optional

`boolean`. Whether the tabs are in the current window.

`discarded` Optional

`boolean`. Whether the tabs are discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content gets reloaded the next time it's activated.

`hidden` Optional

`boolean`. Whether the tabs are hidden.

`highlighted` Optional

`boolean`. Whether the tabs are highlighted.

`index` Optional

`integer`. The position of the tabs within their windows.

`muted` Optional

`boolean`. Whether the tabs are muted.

`lastFocusedWindow` Optional

`boolean`. Whether the tabs are in the last focused window.

`pinned` Optional

`boolean`. Whether the tabs are pinned.

`status` Optional

`tabs.TabStatus`. Whether the tabs have completed loading.

`title` Optional

`string`. Match page titles against a pattern. Requires the "tabs" permission or host permissions for the tab to match.

`url` Optional

`string` or `array` of `string`. Match tabs against one or more match patterns. Note that fragment identifiers are not matched. Requires the "tabs" permission or host permissions for the tab to match.

`windowId` Optional

`integer`. The `id` of the parent window, or `windows.WINDOW_ID_CURRENT` for the current window.

`windowType` Optional

`tabs.WindowType`. The type of window the tabs are in.


### Return value

A `Promise` that will be fulfilled with an `array` of ``tabs.Tab`` objects, containing information about each matching tab.

If any error occurs, the promise will be rejected with an error message.

Examples
--------

Get all tabs:


```js
function logTabs(tabs) {
  for (const tab of tabs) {
    // tab.url requires the `tabs` permission or a matching host permission.
    console.log(tab.url);
  }
}

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

browser.tabs.query({}).then(logTabs, onError);
```


Get all tabs in the current window:


```js
function logTabs(tabs) {
  for (const tab of tabs) {
    // tab.url requires the `tabs` permission or a matching host permission.
    console.log(tab.url);
  }
}

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

browser.tabs.query({ currentWindow: true }).then(logTabs, onError);
```


Get the active tab in the current window:


```js
function logTabs(tabs) {
  // tabs[0].url requires the `tabs` permission or a matching host permission.
  console.log(tabs[0].url);
}

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

browser.tabs
  .query({ currentWindow: true, active: true })
  .then(logTabs, onError);
```


Get tabs for all HTTP and HTTPS URLs under `"mozilla.org"` or any of its subdomains:


```js
function logTabs(tabs) {
  for (const tab of tabs) {
    // tab.url requires the `tabs` permission or a matching host permission.
    console.log(tab.url);
  }
}

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

browser.tabs.query({ url: "\*://\*.mozilla.org/\*" }).then(logTabs, onError);
```

### Example extensions

* annotate-page
* apply-css
* beastify
* bookmark-it
* chill-out
* contextual-identities
* cookie-bg-picker
* find-across-tabs
* history-deleter
* imagify
* list-cookies
* 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.