chrome.tabs

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

Manifest

Almost all chrome.tabs methods require you to declare the "tabs" permission in the extension manifest. For example:

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}

Three methods (create, update and remove) and one event (onRemoved) don't require the "tabs" permission.

Examples

You can find simple examples of using the tabs module in the examples/api/tabs directory. For other examples and for help in viewing the source code, see Samples.

chrome.tabs reference

Types

Tab

Properties of Tab

id ( integer ): The ID of the tab. Tab IDs are unique within a browser session.
index ( integer ): The zero-based index of the tab within its window.
windowId ( integer ): The ID of the window the tab is contained within.
openerTabId ( optional integer ): The ID of the tab that opened this tab, if any. This will only be present if the opener tab still exists.
highlighted ( boolean ): Whether the tab is highlighted.
active ( boolean ): Whether the tab is active in its window.
pinned ( boolean ): Whether the tab is pinned.
url ( optional string ): The URL the tab is displaying. This will only be present if the extension has the 'tabs' or 'webNavigation' permission.
title ( optional string ): The title of the tab. This will only be present if the extension has the 'tabs' or 'webNavigation' permission. It may also be an empty string if the tab is loading.
favIconUrl ( optional string ): The URL of the tab's favicon. This will only be present if the extension has the 'tabs' or 'webNavigation' permission. It may also be an empty string if the tab is loading.
status ( optional string ): Either loading or complete.
incognito ( boolean ): Whether the tab is in an incognito window.

InjectDetails

Details of the script or CSS to inject. Either the code or the file property must be set, but both may not be set at the same time.

Properties of InjectDetails

code ( optional string ): JavaScript or CSS code to inject.
file ( optional string ): JavaScript or CSS file to inject.
allFrames ( optional boolean ): If allFrames is true, implies that the JavaScript or CSS should be injected into all frames of current page. By default, it's false and will only be injected into the top frame.
runAt ( optional enum of "document_start", "document_end", or "document_idle" ): The soonest that the JavaScript or CSS will be injected into the tab. Defaults to "document_idle".

Methods

get

chrome.tabs.get(integer tabId, function callback)

Retrieves details about the specified tab.

Parameters

tabId ( integer )
callback ( function )

Callback

The callback parameter should specify a function that looks like this:

function(Tab tab) {...};

tab ( Tab )

getCurrent

chrome.tabs.getCurrent(function callback)

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).

Parameters

callback ( function )

Callback

The callback parameter should specify a function that looks like this:

function(Tab tab) {...};

tab ( optional Tab )

connect

runtime.Port chrome.tabs.connect(integer tabId, object connectInfo)

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

tabId ( integer )

connectInfo ( optional object )

name ( optional string ): Will be passed into onConnect for content scripts that are listening for the connection event.

sendMessage

chrome.tabs.sendMessage(integer tabId, any message, function responseCallback)

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

tabId ( integer )
message ( any )
responseCallback ( optional function )

Callback

If you specify the responseCallback parameter, it should specify a function that looks like this:

function(any response) {...};

response ( any ): The JSON response object sent by the handler of the message. If an error occurs while connecting to the specified tab, the callback will be called with no arguments and runtime.lastError will be set to the error message.

create

chrome.tabs.create(object createProperties, function callback)

Creates a new tab. Note: This function can be used without requesting the 'tabs' permission in the manifest.

Parameters

createProperties ( object )

windowId ( optional integer ): The window to create the new tab in. Defaults to the current window.
index ( optional integer ): The position the tab should take in the window. The provided value will be clamped to between zero and the number of tabs in the window.
url ( optional string ): The URL to navigate the tab to initially. Fully-qualified URLs must include a scheme (i.e. 'http://www.google.com', not 'www.google.com'). Relative URLs will be relative to the current page within the extension. Defaults to the New Tab Page.
active ( optional boolean ): Whether the tab should become the active tab in the window. Defaults to true
pinned ( optional boolean ): Whether the tab should be pinned. Defaults to false
openerTabId ( optional integer ): The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as the newly created tab.

callback ( optional function )

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function(Tab tab) {...};

tab ( Tab ): Details about the created tab. Will contain the ID of the new tab.

duplicate

chrome.tabs.duplicate(integer tabId, function callback)

Duplicates a tab. Note: This function can be used without requesting the 'tabs' permission in the manifest.

Parameters

tabId ( integer ): The ID of the tab which is to be duplicated.
callback ( optional function )

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function(Tab tab) {...};

tab ( optional Tab ): Details about the duplicated tab. The Tab object doesn't contain url, title and faviconUrl if the 'tabs' permission has not been requested.

query

chrome.tabs.query(object queryInfo, function callback)

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

Parameters

queryInfo ( object )

active ( optional boolean ): Whether the tabs are active in their windows.
pinned ( optional boolean ): Whether the tabs are pinned.
highlighted ( optional boolean ): Whether the tabs are highlighted.
currentWindow ( optional boolean ): Whether the tabs are in the current window.
lastFocusedWindow ( optional boolean ): Whether the tabs are in the last focused window.
status ( optional enum of "loading", or "complete" ): Whether the tabs have completed loading.
title ( optional string ): Match page titles against a pattern.
url ( optional string ): Match tabs against a URL pattern.
windowId ( optional integer ): The ID of the parent window, or windows.WINDOW_ID_CURRENT for the current window.
windowType ( optional enum of "normal", "popup", "panel", or "app" ): The type of window the tabs are in.
index ( optional integer ): The position of the tabs within their windows.

callback ( function )

Callback

The callback parameter should specify a function that looks like this:

function(array of Tab result) {...};

result ( array of Tab )

highlight

chrome.tabs.highlight(object highlightInfo, function callback)

Highlights the given tabs.

Parameters

highlightInfo ( object )

windowId ( optional integer ): The window that contains the tabs.
tabs ( array of integer or integer ): One or more tab indices to highlight.

callback ( function )

Callback

The callback parameter should specify a function that looks like this:

function(windows.Window window) {...};

window ( windows.Window ): Contains details about the window whose tabs were highlighted.

update

chrome.tabs.update(integer tabId, object updateProperties, function callback)

Modifies the properties of a tab. Properties that are not specified in updateProperties are not modified. Note: This function can be used without requesting the 'tabs' permission in the manifest.

Parameters

tabId ( optional integer )

Defaults to the selected tab of the current window.

updateProperties ( object )

url ( optional string ): A URL to navigate the tab to.
active ( optional boolean ): Whether the tab should be active.
highlighted ( optional boolean ): Adds or removes the tab from the current selection.
pinned ( optional boolean ): Whether the tab should be pinned.
openerTabId ( optional integer ): The ID of the tab that opened this tab. If specified, the opener tab must be in the same window as this tab.

callback ( optional function )

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function(Tab tab) {...};

tab ( optional Tab ): Details about the updated tab, or null if the 'tabs' permission has not been requested.

move

chrome.tabs.move(integer or array of integer tabIds, object moveProperties, function callback)

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 ( integer or array of integer )

The tab or list of tabs to move.

moveProperties ( object )

windowId ( optional integer ): Defaults to the window the tab is currently in.
index ( integer ): The position to move the window to. -1 will place the tab at the end of the window.

callback ( optional function )

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function(Tab or array of Tab tabs) {...};

tabs ( Tab or array of Tab ): Details about the moved tabs.

reload

chrome.tabs.reload(integer tabId, object reloadProperties, function callback)

Reload a tab.

Parameters

tabId ( optional integer )

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

reloadProperties ( optional object )

bypassCache ( optional boolean ): Whether using any local cache. Default is false.

callback ( optional function )

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

remove

chrome.tabs.remove(integer or array of integer tabIds, function callback)

Closes one or more tabs. Note: This function can be used without requesting the 'tabs' permission in the manifest.

Parameters

tabIds ( integer or array of integer ): The tab or list of tabs to close.
callback ( optional function )

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

detectLanguage

chrome.tabs.detectLanguage(integer tabId, function callback)

Detects the primary language of the content in a tab.

Parameters

tabId ( optional integer ): Defaults to the active tab of the current window.
callback ( function )

Callback

The callback parameter should specify a function that looks like this:

function(string language) {...};

language ( string ): An ISO language code such as en or fr. For a complete list of languages supported by this method, see kLanguageInfoTable. The 2nd to 4th columns will be checked and the first non-NULL value will be returned except for Simplified Chinese for which zh-CN will be returned. For an unknown language, und will be returned.

captureVisibleTab

chrome.tabs.captureVisibleTab(integer windowId, object options, function callback)

Captures the visible area of the currently active tab in the specified window. You must have host permission for the URL displayed by the tab.

Parameters

windowId ( optional integer )

The target window. Defaults to the current window.

options ( optional object )

Set parameters of image capture, such as the format of the resulting image.

format ( optional enum of "jpeg", or "png" ): The format of the resulting image. Default is jpeg.
quality ( optional integer ): When format is 'jpeg', controls the quality of the resulting image. This value is ignored for PNG images. As quality is decreased, the resulting image will have more visual artifacts, and the number of bytes needed to store it will decrease.

callback ( function )

Callback

The callback parameter should specify a function that looks like this:

function(string dataUrl) {...};

dataUrl ( string ): A data URL which encodes an image of the visible area of the captured tab. May be assigned to the 'src' property of an HTML Image element for display.

executeScript

chrome.tabs.executeScript(integer tabId, InjectDetails details, function callback)

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

Parameters

tabId ( optional integer ): 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.
callback ( optional function ): Called after all the JavaScript has been executed.

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function(array of any result) {...};

result ( optional array of any ): The result of the script in every injected frame.

insertCSS

chrome.tabs.insertCSS(integer tabId, InjectDetails details, function callback)

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

Parameters

tabId ( optional integer ): 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.
callback ( optional function ): Called when all the CSS has been inserted.

Callback

If you specify the callback parameter, it should specify a function that looks like this:

function() {...};

Events

onCreated

chrome.tabs.onCreated.addListener(function(Tab tab) {...});

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.

Listener Parameters

tab ( Tab ): Details of the tab that was created.

onUpdated

chrome.tabs.onUpdated.addListener(function(integer tabId, object changeInfo, Tab tab) {...});

Fired when a tab is updated.

Listener Parameters

tabId ( integer )

changeInfo ( object )

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

status ( optional string ): The status of the tab. Can be either loading or complete.
url ( optional string ): The tab's URL if it has changed.
pinned ( optional boolean ): The tab's new pinned state.

tab ( Tab )

Gives the state of the tab that was updated.

onMoved

chrome.tabs.onMoved.addListener(function(integer tabId, object moveInfo) {...});

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 onDetached.

Listener Parameters

tabId ( integer )

moveInfo ( object )

windowId ( integer )
fromIndex ( integer )
toIndex ( integer )

onActivated

chrome.tabs.onActivated.addListener(function(object activeInfo) {...});

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.

Listener Parameters

activeInfo ( object )

tabId ( integer ): The ID of the tab that has become active.
windowId ( integer ): The ID of the window the active tab changed inside of.

onHighlighted

chrome.tabs.onHighlighted.addListener(function(object highlightInfo) {...});

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

Listener Parameters

highlightInfo ( object )

windowId ( integer ): The window whose tabs changed.
tabIds ( array of integer ): All highlighted tabs in the window.

onDetached

chrome.tabs.onDetached.addListener(function(integer tabId, object detachInfo) {...});

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

Listener Parameters

tabId ( integer )

detachInfo ( object )

oldWindowId ( integer )
oldPosition ( integer )

onAttached

chrome.tabs.onAttached.addListener(function(integer tabId, object attachInfo) {...});

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

Listener Parameters

tabId ( integer )

attachInfo ( object )

newWindowId ( integer )
newPosition ( integer )

onRemoved

chrome.tabs.onRemoved.addListener(function(integer tabId, object removeInfo) {...});

Fired when a tab is closed. Note: A listener can be registered for this event without requesting the 'tabs' permission in the manifest.

Listener Parameters

tabId ( integer )

removeInfo ( object )

windowId ( integer ): the window whose tab is closed.
isWindowClosing ( boolean ): True when the tab is being closed because its window is being closed.

onReplaced

chrome.tabs.onReplaced.addListener(function(integer addedTabId, integer removedTabId) {...});

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

Listener Parameters

addedTabId ( integer )
removedTabId ( integer )

Sample Extensions that use chrome.tabs

My Bookmarks – A browser action with a popup dump of all bookmarks, including search, add, edit and delete.

Page Redder

Print this page – Adds a print button to the browser.

A browser action with a popup that changes the page color.

Cookie API Test Extension – Testing Cookie API

Broken Links – Extends the Developer Tools, adding an audit category that finds broken links on the inspected page.

FirePHP for Chrome – Extends the Developer Tools, adding support for parsing FirePHP messages from server

Download Selected Links – Select links on a page and download them.

Event Page Example – Demonstrates usage and features of the event page

Typed URL History – Reads your history, and shows the top ten pages you go to by typing the URL.

Time filter for History – Reads your history, and shows top pages you visited in the time +/-1 hour in the last two months

CLD – Displays the language of a tab

Message Timer – Times how long it takes to send a message to a content script and back.

Page action by URL – Shows a page action for urls which have the letter 'g' in them.

Top Chrome Extension Questions – Sample demonstration of the optional permissions API.

Show Tabs in Process – Adds a browser action showing which tabs share the current tab's process.

Stylizr – Spruce up your pages with custom CSS.

Tab Inspector – Utility for working with the extension tabs api

Keyboard Pin – Creates a keyboard shortcut (Alt + Shift + P) to toggle the pinned state of the currently selected tab

Test Screenshot Extension – Demonstrate screenshot functionality in the chrome.tabs api. Note: only works for code.google.com

Merge Windows – Merges all of the browser's windows into the current window

App Launcher

Page Benchmarker – Chromium Page Benchmarker.

Google Calendar Checker (by Google) – Quickly see the time until your next meeting from any of your calendars. Click on the button to be taken to your calendar.

Chromium Search – Add support to the omnibox to search the Chromium source code.

Email this page (by Google) – This extension adds an email button to the toolbar which allows you to email the page link using your default mail client or Gmail.

Chrome Sounds – Enjoy a more magical and immersive experience when browsing the web using the power of sound.

Google Document List Viewer – Demonstrates how to use OAuth to connect the Google Documents List Data API.

Google Mail Checker – Displays the number of unread messages in your Google Mail inbox. You can also click the button to open your inbox.

Imageinfo – Get image info for images, including EXIF data

Mappy – Finds addresses in the web page you're on and pops up a map window.

News Reader (by Google) – Displays the latest stories from Google News in a popup.

News Reader – Displays the first 5 items from the 'Google News - top news' RSS feed in a popup.

Sample - OAuth Contacts – Uses OAuth to connect to Google's contacts service and display a list of your contacts.

Speak Selection – Speaks the current selection out loud.

Jan	APR	Jun
	30
2012	2013	2014