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
. Thequery()
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 istrue
. When set tofalse
, the browser cannot automatically discard the tab. However, the tab can be discarded bytabs.discard
. -
string
orarray
ofstring
. Use this to return tabs whosetab.cookieStoreId
matches any of thecookieStoreId
strings. This option is only available if the add-on has the"cookies"
permission. 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. -
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
orarray
ofstring
. 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
. Theid
of the parent window, orwindows.WINDOW_ID_CURRENT
for the current window. windowType
Optional-
tabs.WindowType
. The type of window the tabs are in.
Return value
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
Browser compatibility
BCD tables only load in the browser
Note: This API is based on Chromium's chrome.tabs
API. This documentation is derived from tabs.json
in the Chromium code.