Use the browser.tabs API to interact with the browser's tab system. You can use this API to create, modify, and rearrange tabs in the browser.

Not allowed in: Content scripts, Devtools pages

_ConnectConnectInfo
_CreateCreateProperties
_DuplicateDuplicateProperties
_HighlightHighlightInfo
_MoveInSuccessionOptions
_MoveMoveProperties
_OnActivatedActiveInfo
_OnAttachedAttachInfo
_OnDetachedDetachInfo
_OnHighlightedHighlightInfo
_OnMovedMoveInfo
_OnRemovedRemoveInfo
_OnUpdatedChangeInfo
_OnZoomChangeZoomChangeInfo
_QueryQueryInfo
_ReloadReloadProperties
_SendMessageOptions
_TabsOnUpdatedEvent
_UpdateUpdateProperties
MutedInfo
PageSettings
SharingState
Tab
UpdateFilter
ZoomSettings
_QueryQueryInfoScreen
MutedInfoReason
TabStatus
UpdatePropertyName
WindowType
ZoomSettingsMode
ZoomSettingsScope
onActivated
onAttached
onCreated
onDetached
onHighlighted
onMoved
onRemoved
onReplaced
onUpdated
onZoomChange
TAB_ID_NONE
captureTab
captureVisibleTab
connect
create
detectLanguage
discard
duplicate
executeScript
get
getCurrent
getZoom
getZoomSettings
goBack
goForward
hide
highlight
insertCSS
move
moveInSuccession
printPreview
query
reload
remove
removeCSS
saveAsPDF
sendMessage
setZoom
setZoomSettings
show
toggleReaderMode
update
warmup

_QueryQueryInfoScreen

_QueryQueryInfoScreen: "Screen" | "Window" | "Application"
MutedInfoReason: "user" | "capture" | "extension"

An event that caused a muted state change.

Type Declaration

  • "user"

    A user input action has set/overridden the muted state.

  • "capture"

    Tab capture started, forcing a muted state change.

  • "extension"

    An extension, identified by the extensionId field, set the muted state.

TabStatus: "loading" | "complete"

Whether the tabs have completed loading.

UpdatePropertyName:
    | "attention"
    | "audible"
    | "autoDiscardable"
    | "discarded"
    | "favIconUrl"
    | "hidden"
    | "isArticle"
    | "mutedInfo"
    | "pinned"
    | "sharingState"
    | "status"
    | "title"
    | "url"

Event names supported in onUpdated.

WindowType: "normal" | "popup" | "panel" | "app" | "devtools"

The type of window.

ZoomSettingsMode: "automatic" | "manual" | "disabled"

Defines how zoom changes are handled, i.e. which entity is responsible for the actual scaling of the page; defaults to automatic.

Type Declaration

  • "automatic"

    Zoom changes are handled automatically by the browser.

  • "manual"

    Overrides the automatic handling of zoom changes. The onZoomChange event will still be dispatched, and it is the responsibility of the extension to listen for this event and manually scale the page. This mode does not support per-origin zooming, and will thus ignore the scope zoom setting and assume per-tab.

  • "disabled"

    Disables all zooming in the tab. The tab will revert to the default zoom level, and all attempted zoom changes will be ignored.

ZoomSettingsScope: "per-origin" | "per-tab"

Defines whether zoom changes will persist for the page's origin, or only take effect in this tab; defaults to per-origin when in automatic mode, and per-tab otherwise.

Type Declaration

  • "per-origin"

    Zoom changes will persist in the zoomed page's origin, i.e. all other tabs navigated to that same origin will be zoomed as well. Moreover, per-origin zoom changes are saved with the origin, meaning that when navigating to other pages in the same origin, they will all be zoomed to the same zoom factor. The per-origin scope is only available in the automatic mode.

  • "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, per-tab zoom changes are reset on navigation; navigating a tab will always load pages with their per-origin zoom factors.

onActivated: WebExtEvent<(activeInfo: _OnActivatedActiveInfo) => void>

Fires when the active 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 onUpdated events to be notified when a URL is set.

onAttached: WebExtEvent<
    (tabId: number, attachInfo: _OnAttachedAttachInfo) => void,
>

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

onCreated: WebExtEvent<(tab: Tab) => void>

Fired when a tab is created. Note that the tab's URL may not be set at the time this event fired, but you can listen to onUpdated events to be notified when a URL is set.

Details of the tab that was created.

onDetached: WebExtEvent<
    (tabId: number, detachInfo: _OnDetachedDetachInfo) => void,
>

Fired when a tab is detached from a window, for example because it is being moved between windows.

onHighlighted: WebExtEvent<(highlightInfo: _OnHighlightedHighlightInfo) => void>

Fired when the highlighted or selected tabs in a window changes.

onMoved: WebExtEvent<
    (tabId: number, moveInfo: browser.tabs._OnMovedMoveInfo) => void,
>

Fired when a tab is moved within a window. Only one move event is fired, representing the tab the user directly moved. Move events are not fired for the other tabs that must move in response. This event is not fired when a tab is moved between windows. For that, see tabs.onDetached.

onRemoved: WebExtEvent<
    (tabId: number, removeInfo: browser.tabs._OnRemovedRemoveInfo) => void,
>

Fired when a tab is closed.

onReplaced: WebExtEvent<(addedTabId: number, removedTabId: number) => void>

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

onUpdated: _TabsOnUpdatedEvent

Fired when a tab is updated.

Lists the changes to the state of the tab that was updated.

Gives the state of the tab that was updated.

onZoomChange: WebExtEvent<(ZoomChangeInfo: _OnZoomChangeZoomChangeInfo) => void>

Fired when a tab is zoomed.

TAB_ID_NONE: number

An ID which represents the absence of a browser tab.

  • Captures an area of a specified tab. You must have <all_urls> permission to use this method.

    Returns Promise<string>

  • Captures an area of a specified tab. You must have <all_urls> permission to use this method.

    Parameters

    • tabId: number

      The tab to capture. Defaults to the active tab of the current window.

    • Optionaloptions: ImageDetails

    Returns Promise<string>

  • Captures an area of a specified tab. You must have <all_urls> permission to use this method.

    Parameters

    Returns Promise<string>

  • Captures an area of the currently active tab in the specified window. You must have <all_urls> permission to use this method.

    Returns Promise<string>

  • Captures an area of the currently active tab in the specified window. You must have <all_urls> permission to use this method.

    Parameters

    • windowId: number

      The target window. Defaults to the current window.

    • Optionaloptions: ImageDetails

    Returns Promise<string>

  • Captures an area of the currently active tab in the specified window. You must have <all_urls> permission to use this method.

    Parameters

    Returns Promise<string>

  • Connects to the content script(s) in the specified tab. The runtime.onConnect event is fired in each content script running in the specified tab for the current extension. For more details, see Content Script Messaging.

    Parameters

    Returns Port

    A port that can be used to communicate with the content scripts running in the specified tab. The port's runtime.Port event is fired if the tab closes or does not exist.

  • Detects the primary language of the content in a tab.

    Parameters

    • OptionaltabId: number

      Defaults to the active tab of the current window.

    Returns Promise<string>

  • discards one or more tabs.

    Parameters

    • tabIds: number | number[]

      The tab or list of tabs to discard.

    Returns Promise<void>

  • Duplicates a tab.

    Parameters

    Returns Promise<Tab>

  • Injects JavaScript code into a page. For details, see the programmatic injection section of the content scripts doc.

    Parameters

    • details: InjectDetails

      Details of the script to run. Not supported on manifest versions above 2.

    Returns Promise<any[]>

  • Injects JavaScript code into a page. For details, see the programmatic injection section of the content scripts doc.

    Parameters

    • tabId: number

      The ID of the tab in which to run the script; defaults to the active tab of the current window.

    • details: InjectDetails

      Details of the script to run. Not supported on manifest versions above 2.

    Returns Promise<any[]>

  • Retrieves details about the specified tab.

    Parameters

    • tabId: number

    Returns Promise<Tab>

  • Gets the tab that this script call is being made from. May be undefined if called from a non-tab context (for example: a background page or popup view).

    Returns Promise<Tab>

  • Gets the current zoom factor of a specified tab.

    Parameters

    • OptionaltabId: number

      The ID of the tab to get the current zoom factor from; defaults to the active tab of the current window.

    Returns Promise<number>

  • Gets the current zoom settings of a specified tab.

    Parameters

    • OptionaltabId: number

      The ID of the tab to get the current zoom settings from; defaults to the active tab of the current window.

    Returns Promise<ZoomSettings>

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

    Parameters

    • OptionaltabId: number

      The ID of the tab to navigate backward.

    Returns Promise<void>

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

    Parameters

    • OptionaltabId: number

      The ID of the tab to navigate forward.

    Returns Promise<void>

  • Hides one or more tabs. The "tabHide" permission is required to hide tabs. Not all tabs are hidable. Returns an array of hidden tabs.

    Parameters

    • tabIds: number | number[]

      The TAB ID or list of TAB IDs to hide.

    Returns Promise<number[]>

  • Injects CSS into a page. For details, see the programmatic injection section of the content scripts doc.

    Parameters

    • details: InjectDetails

      Details of the CSS text to insert. Not supported on manifest versions above 2.

    Returns Promise<void>

  • Injects CSS into a page. For details, see the programmatic injection section of the content scripts doc.

    Parameters

    • tabId: number

      The ID of the tab in which to insert the CSS; defaults to the active tab of the current window.

    • details: InjectDetails

      Details of the CSS text to insert. Not supported on manifest versions above 2.

    Returns Promise<void>

  • Moves one or more tabs to a new position within its window, or to a new window. Note that tabs can only be moved to and from normal (window.type === "normal") windows.

    Parameters

    • tabIds: number | number[]

      The tab or list of tabs to move.

    • moveProperties: _MoveMoveProperties

    Returns Promise<Tab | Tab[]>

  • Removes an array of tabs from their lines of succession and prepends or appends them in a chain to another tab.

    Parameters

    • tabIds: number[]

      An array of tab IDs to move in the line of succession. For each tab in the array, the tab's current predecessors will have their successor set to the tab's current successor, and each tab will then be set to be the successor of the previous tab in the array. Any tabs not in the same window as the tab indicated by the second argument (or the first tab in the array, if no second argument) will be skipped.

    • OptionaltabId: number

      The ID of a tab to set as the successor of the last tab in the array, or tabs.TAB_ID_NONE to leave the last tab without a successor. If options.append is true, then this tab is made the predecessor of the first tab in the array instead.

    • Optionaloptions: _MoveInSuccessionOptions

    Returns Promise<any>

  • Prints page in active tab.

    Returns void

  • Shows print preview for page in active tab.

    Returns Promise<void>

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

    Parameters

    Returns Promise<Tab[]>

  • Reload a tab.

    Returns Promise<void>

  • Reload a tab.

    Parameters

    • tabId: number

      The ID of the tab to reload; defaults to the selected tab of the current window.

    • OptionalreloadProperties: _ReloadReloadProperties

    Returns Promise<void>

  • Reload a tab.

    Parameters

    Returns Promise<void>

  • Closes one or more tabs.

    Parameters

    • tabIds: number | number[]

      The tab or list of tabs to close.

    Returns Promise<void>

  • Removes injected CSS from a page. For details, see the programmatic injection section of the content scripts doc.

    Parameters

    • details: InjectDetails

      Details of the CSS text to remove. Not supported on manifest versions above 2.

    Returns Promise<void>

  • Removes injected CSS from a page. For details, see the programmatic injection section of the content scripts doc.

    Parameters

    • tabId: number

      The ID of the tab from which to remove the injected CSS; defaults to the active tab of the current window.

    • details: InjectDetails

      Details of the CSS text to remove. Not supported on manifest versions above 2.

    Returns Promise<void>

  • Saves page in active tab as a PDF file.

    Parameters

    • pageSettings: PageSettings

      The page settings used to save the PDF file.

    Returns Promise<string>

  • Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back. The runtime.onMessage event is fired in each content script running in the specified tab for the current extension.

    Parameters

    Returns Promise<any>

  • Zooms a specified tab.

    Parameters

    • zoomFactor: number

      The new zoom factor. Use a value of 0 here to set the tab to its current default zoom factor. Values greater than zero specify a (possibly non-default) zoom factor for the tab.

    Returns Promise<void>

  • Zooms a specified tab.

    Parameters

    • tabId: number

      The ID of the tab to zoom; defaults to the active tab of the current window.

    • zoomFactor: number

      The new zoom factor. Use a value of 0 here to set the tab to its current default zoom factor. Values greater than zero specify a (possibly non-default) zoom factor for the tab.

    Returns Promise<void>

  • Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab.

    Parameters

    • zoomSettings: ZoomSettings

      Defines how zoom changes are handled and at what scope.

    Returns Promise<void>

  • Sets the zoom settings for a specified tab, which define how zoom changes are handled. These settings are reset to defaults upon navigating the tab.

    Parameters

    • tabId: number

      The ID of the tab to change the zoom settings for; defaults to the active tab of the current window.

    • zoomSettings: ZoomSettings

      Defines how zoom changes are handled and at what scope.

    Returns Promise<void>

  • Shows one or more tabs.

    Parameters

    • tabIds: number | number[]

      The TAB ID or list of TAB IDs to show.

    Returns Promise<void>

  • Toggles reader mode for the document in the tab.

    Parameters

    • OptionaltabId: number

      Defaults to the active tab of the current window.

    Returns Promise<void>

  • Modifies the properties of a tab. Properties that are not specified in updateProperties are not modified.

    Parameters

    Returns Promise<Tab>

  • Modifies the properties of a tab. Properties that are not specified in updateProperties are not modified.

    Parameters

    Returns Promise<Tab>

  • Warm up a tab

    Parameters

    • tabId: number

      The ID of the tab to warm up.

    Returns Promise<any>