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.

API Reference: chrome.tabs

Types

Tab

( object )

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

( object )

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 enumerated string ["document_start", "document_end", "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)

Retrieves details about the specified tab.

Parameters

tabId ( integer )

Callback function

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

function(Tab tab) {...};

tab ( Tab )

getCurrent

chrome.tabs.getCurrent()

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

connect

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

Connects to the content script(s) in the specified tab. The chrome.extension.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)

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 chrome.extension.onMessage event is fired in each content script running in the specified tab for the current extension.

Parameters

tabId ( integer )
message ( any )

Callback function

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 chrome.extension.lastError will be set to the error message.

create

chrome.tabs.create(object createProperties)

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 function

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)

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 function

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)

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 enumerated string ["loading", "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 chrome.windows.WINDOW_ID_CURRENT for the current window.
windowType ( optional enumerated string ["normal", "popup", "panel", "app"] ): The type of window the tabs are in.
index ( optional integer ): The position of the tabs within their windows.

Callback function

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)

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

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)

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 function

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(array of integer or integer tabIds, object moveProperties)

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

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

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

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

reload

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

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 function

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

function() {...};

remove

chrome.tabs.remove(array of integer or integer tabIds)

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

Parameters

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

Callback function

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

function() {...};

detectLanguage

chrome.tabs.detectLanguage(integer tabId)

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

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)

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 enumerated string ["jpeg", "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

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)

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 function

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)

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 function

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 )

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

Sample Extensions that use chrome.tabs

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

A browser action with no icon that makes the page red –

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.

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 –

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.

Google Chrome Extensions

chrome.tabs

Contents

Manifest

Examples

API Reference: chrome.tabs

Types

Tab

Properties of Tab

InjectDetails

Properties of InjectDetails

Methods

get

Parameters

Callback function

getCurrent

connect

Parameters

sendMessage

Parameters

Callback function

create

Parameters

Callback function

duplicate

Parameters

Callback function

query

Parameters

Callback function

highlight

Parameters

Callback function

update

Parameters

Callback function

move

Parameters

Callback function

reload

Parameters

Callback function

remove

Parameters

Callback function

detectLanguage

Parameters

Callback function

captureVisibleTab

Parameters

Callback function

executeScript

Parameters

Callback function

insertCSS

Parameters

Callback function

Events

onCreated

Listener Parameters

onUpdated

Listener Parameters

onMoved

Listener Parameters

onActivated

Listener Parameters

onHighlighted

Listener Parameters

onDetached

Listener Parameters

onAttached

Listener Parameters

onRemoved

Listener Parameters

Sample Extensions that use chrome.tabs