tabs.md

tabs

Documentation: Chrome Tabs API

A promise-based wrapper for the Chrome tabs API, providing core tab operations, messaging, zoom controls, grouping, and helper utilities.

Methods

• captureVisibleTab(windowId, options)
• connectTab(tabId, connectInfo?)
• createTab(properties)
• detectTabLanguage(tabId)
• discardTab(tabId)
• duplicateTab(tabId)
• getTab(tabId)
• getCurrentTab()
• getTabZoom(tabId)
• getTabZoomSettings(tabId)
• goTabBack(tabId)
• goTabForward(tabId)
• groupTabs(options)
• highlightTab(highlightInfo)
• moveTab(tabId, moveProperties)
• moveTabs(tabIds, moveProperties)
• queryTabs(queryInfo?)
• reloadTab(tabId, bypassCache?)
• removeTab(tabId)
• sendTabMessage(tabId, message, options?)
• setTabZoom(tabId, zoomFactor)
• setTabZoomSettings(tabId, zoomSettings)
• ungroupTab(tabIds)
• updateTab(tabId, updateProperties)
• executeScriptTab(tabId, details) [MV2]
• insertCssTab(tabId, details) [MV2]
• removeCssTab(tabId, details) [MV2]
• getTabUrl(tabId)
• getActiveTab()
• queryTabIds(queryInfo?)
• findTab(queryInfo?)
• findTabById(tabId)
• findTabByUrl(url)
• updateTabAsSelected(tabId)
• updateTabAsActive(tabId)
• openOrCreateTab(tab)
• openOrCreateTabByUrl(url)

Events

• onTabActivated(callback)
• onTabAttached(callback)
• onTabCreated(callback)
• onTabDetached(callback)
• onTabHighlighted(callback)
• onTabMoved(callback)
• onTabRemoved(callback)
• onTabReplaced(callback)
• onTabUpdated(callback)
• onTabZoomChange(callback)

---

captureVisibleTab

captureVisibleTab(
  windowId: number,
  options: chrome.extensionTypes.ImageDetails
): Promise<string>

Captures the visible area of the specified window as an image (data URL string).

connectTab

connectTab(
  tabId: number,
  connectInfo?: chrome.tabs.ConnectInfo
): chrome.runtime.Port

Creates a long-lived connection to the specified tab for messaging.

createTab

createTab(properties: chrome.tabs.CreateProperties): Promise<chrome.tabs.Tab>

Creates a new tab with the given properties.

detectTabLanguage

detectTabLanguage(tabId: number): Promise<string>

Detects the primary language of the specified tab's content. Returns a language code (e.g., "en" or "und").

discardTab

discardTab(tabId: number): Promise<chrome.tabs.Tab | undefined>

Discards the specified tab to free memory. Resolves with the updated tab or undefined.

duplicateTab

duplicateTab(tabId: number): Promise<chrome.tabs.Tab | undefined>

Duplicates the specified tab. Resolves with the new tab, or undefined if duplication fails.

getTab

getTab(tabId: number): Promise<chrome.tabs.Tab>

Retrieves information about the specified tab.

getCurrentTab

getCurrentTab(): Promise<chrome.tabs.Tab | undefined>

Retrieves the tab in which the calling script is running (e.g., popup). May resolve to undefined outside a tab context.

getTabZoom

getTabZoom(tabId: number): Promise<number>

Gets the zoom factor of the specified tab.

getTabZoomSettings

getTabZoomSettings(tabId: number): Promise<chrome.tabs.ZoomSettings>

Retrieves the zoom settings for the specified tab.

goTabBack

goTabBack(tabId: number): Promise<void>

Navigates the tab one step backward in its history.

goTabForward

goTabForward(tabId: number): Promise<void>

Navigates the tab one step forward in its history.

groupTabs

groupTabs(options: chrome.tabs.GroupOptions): Promise<number>

Groups one or more tabs. Resolves with the group ID.

highlightTab

highlightTab(highlightInfo: chrome.tabs.HighlightInfo): Promise<chrome.windows.Window>

Highlights (selects) the specified tabs and resolves with the updated window.

moveTab

moveTab(
  tabId: number,
  moveProperties: chrome.tabs.MoveProperties
): Promise<chrome.tabs.Tab>

Moves a tab to a new index or window.

moveTabs

moveTabs(
  tabIds: number[],
  moveProperties: chrome.tabs.MoveProperties
): Promise<chrome.tabs.Tab[]>

Moves multiple tabs and resolves with the updated tabs.

queryTabs

queryTabs(queryInfo?: chrome.tabs.QueryInfo): Promise<chrome.tabs.Tab[]>

Retrieves tabs matching the query filter.

reloadTab

reloadTab(tabId: number, bypassCache?: boolean): Promise<void>

Reloads the specified tab. Set bypassCache to true to force revalidation.

removeTab

removeTab(tabId: number): Promise<void>

Closes the specified tab.

sendTabMessage

sendTabMessage<M = any, R = any>(
  tabId: number,
  message: M,
  options?: chrome.tabs.MessageSendOptions
): Promise<R>

Sends a one-time message to the content script in the specified tab and resolves with the response.

setTabZoom

setTabZoom(tabId: number, zoomFactor: number): Promise<void>

Sets the zoom factor for the specified tab.

setTabZoomSettings

setTabZoomSettings(
  tabId: number,
  zoomSettings: chrome.tabs.ZoomSettings
): Promise<void>

Updates the zoom settings for the specified tab.

ungroupTab

ungroupTab(tabIds: number | [number, ...number[]]): Promise<void>

Removes one or more tabs from their respective groups.

updateTab

updateTab(
  tabId: number,
  updateProperties: chrome.tabs.UpdateProperties
): Promise<chrome.tabs.Tab | undefined>

Updates properties of the specified tab. Resolves with the updated tab or undefined.

executeScriptTab [MV2]

executeScriptTab(
  tabId: number,
  details: chrome.extensionTypes.InjectDetails
): Promise<any[] | undefined>

Executes code in the tab using the MV2 chrome.tabs.executeScript. Not available in MV3.

insertCssTab [MV2]

insertCssTab(
  tabId: number,
  details: chrome.extensionTypes.InjectDetails
): Promise<void>

Inserts CSS into the tab using the MV2 chrome.tabs.insertCSS. Not available in MV3.

removeCssTab [MV2]

removeCssTab(
  tabId: number,
  details: chrome.extensionTypes.InjectDetails
): Promise<void>

Removes previously inserted CSS using the MV2 chrome.tabs.removeCSS. Not available in MV3.

getTabUrl

getTabUrl(tabId: number): Promise<string>

Returns the current URL of the specified tab or throws if it cannot be determined.

getActiveTab

getActiveTab(): Promise<chrome.tabs.Tab>

Returns the active tab in the current window or throws if not found.

queryTabIds

queryTabIds(queryInfo?: chrome.tabs.QueryInfo): Promise<number[]>

Returns only the IDs for tabs matching the query.

findTab

findTab(queryInfo?: chrome.tabs.QueryInfo): Promise<chrome.tabs.Tab | undefined>

Returns the first tab matching the query, if any.

findTabById

findTabById(tabId: number): Promise<chrome.tabs.Tab | undefined>

Resolves with the tab for the given ID, or undefined if not available.

findTabByUrl

findTabByUrl(url: string): Promise<chrome.tabs.Tab | undefined>

Finds the first tab with the specified URL, if any.

updateTabAsSelected

updateTabAsSelected(tabId: number): Promise<chrome.tabs.Tab | undefined>

Marks the specified tab as highlighted (selected).

updateTabAsActive

updateTabAsActive(tabId: number): Promise<chrome.tabs.Tab | undefined>

Marks the specified tab as active.

openOrCreateTab

openOrCreateTab(tab: chrome.tabs.Tab): Promise<void>

Selects an existing tab with the same URL and ID, or creates a new one with that URL.

openOrCreateTabByUrl

openOrCreateTabByUrl(url: string): Promise<void>

Selects an existing tab with the given URL, or creates a new tab with that URL.

---

onTabActivated

onTabActivated(
  callback: (activeInfo: chrome.tabs.OnActivatedInfo) => void
): () => void

Fires when the active tab in a window changes. Returns an unsubscribe function.

onTabAttached

onTabAttached(
  callback: (tabId: number, attachInfo: chrome.tabs.OnAttachedInfo) => void
): () => void

Fires when a tab is attached to a window (moved between windows). Returns an unsubscribe function.

onTabCreated

onTabCreated(
  callback: (tab: chrome.tabs.Tab) => void
): () => void

Fires when a tab is created. Returns an unsubscribe function.

onTabDetached

onTabDetached(
  callback: (tabId: number, detachInfo: chrome.tabs.OnDetachedInfo) => void
): () => void

Fires when a tab is detached from a window. Returns an unsubscribe function.

onTabHighlighted

onTabHighlighted(
  callback: (highlightInfo: chrome.tabs.OnHighlightedInfo) => void
): () => void

Fires when the highlighted/selected tabs in a window change. Returns an unsubscribe function.

onTabMoved

onTabMoved(
  callback: (tabId: number, moveInfo: chrome.tabs.OnMovedInfo) => void
): () => void

Fires when a tab is moved within a window. Returns an unsubscribe function.

onTabRemoved

onTabRemoved(
  callback: (tabId: number, removeInfo: chrome.tabs.OnRemovedInfo) => void
): () => void

Fires when a tab is closed. Returns an unsubscribe function.

onTabReplaced

onTabReplaced(
  callback: (addedTabId: number, removedTabId: number) => void
): () => void

Fires when a tab is replaced with another tab due to prerendering or instant. Returns an unsubscribe function.

onTabUpdated

onTabUpdated(
  callback: (
    tabId: number,
    changeInfo: chrome.tabs.OnUpdatedInfo,
    tab: chrome.tabs.Tab
  ) => void
): () => void

Fires when a tab is updated. Returns an unsubscribe function.

onTabZoomChange

onTabZoomChange(
  callback: (ZoomChangeInfo: chrome.tabs.OnZoomChangeInfo) => void
): () => void

Fires when a tab's zoom changes. Returns an unsubscribe function.