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

status ( optional string ): Either loading or complete.
index ( integer ): The zero-based index of the tab within its window.
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.
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.
url ( optional string ): The URL the tab is displaying. This will only be present if the extension has the 'tabs' or 'webNavigation' permission.
pinned ( boolean ): Whether the tab is pinned.
highlighted ( boolean ): Whether the tab is highlighted.
windowId ( integer ): The ID of the window the tab is contained within.
active ( boolean ): Whether the tab is active in its window.
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.
id ( integer ): The ID of the tab. Tab IDs are unique within a browser session.
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

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.
code ( optional string ): JavaScript or CSS code to inject.
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".
file ( optional string ): JavaScript or CSS file to inject.

Methods

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.

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

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.

get

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

Retrieves details about the specified tab.

Parameters

tabId ( integer )

callback ( function )

tab ( Tab )

Callback function

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 )

tab ( optional Tab )

Callback function

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

function(Tab tab) {...};

tab ( optional Tab )

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 )

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.
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.
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.
pinned ( optional boolean ): Whether the tab should be pinned. Defaults to false
windowId ( optional integer ): The window to create the new tab in. Defaults to the current window.
active ( optional boolean ): Whether the tab should become the active tab in the window. Defaults to true

callback ( optional function )

tab ( Tab ): Details about the created tab. Will contain the ID of the new 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.

move

chrome.tabs.move(array of integer or 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 ( array of integer or integer )

The tab or list of tabs to move.

moveProperties ( object )

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

callback ( optional function )

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

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.

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 )

pinned ( optional boolean ): Whether the tab should be pinned.
url ( optional string ): A URL to navigate the tab to.
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.
highlighted ( optional boolean ): Adds or removes the tab from the current selection.
active ( optional boolean ): Whether the tab should be active.

callback ( optional function )

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

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.

remove

chrome.tabs.remove(array of integer or 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 ( array of integer or integer ): The tab or list of tabs to close.
callback ( optional function )

Callback function

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

function() {...};

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.

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.
format ( optional enumerated string ["jpeg", "png"] ): The format of the resulting image. Default is jpeg.

callback ( function )

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.

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.

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 function

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

function() {...};

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 )

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.

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.

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

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.

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.

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.

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 function

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

function() {...};

highlight

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

Highlights the given tabs.

Parameters

highlightInfo ( object )

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

callback ( function )

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

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.

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 )

status ( optional enumerated string ["loading", "complete"] ): Whether the tabs have completed loading.
index ( optional integer ): The position of the tabs within their windows.
title ( optional string ): Match page titles against a pattern.
url ( optional string ): Match tabs against a URL pattern.
currentWindow ( optional boolean ): Whether the tabs are in the current window.
highlighted ( optional boolean ): Whether the tabs are highlighted.
lastFocusedWindow ( optional boolean ): Whether the tabs are in the last focused window.
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.
active ( optional boolean ): Whether the tabs are active in their windows.
pinned ( optional boolean ): Whether the tabs are pinned.

callback ( function )

result ( array of Tab )

Callback function

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

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

result ( array of Tab )

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 )

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.

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.

Events

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.

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.

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.
pinned ( optional boolean ): The tab's new pinned state.
url ( optional string ): The tab's URL if it has changed.

tab ( Tab )

Gives the state of the tab that was updated.

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 )

newPosition ( integer )
newWindowId ( integer )

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 )

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

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 )

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.

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.

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

Content settings – Shows the content settings for the current site.

Cookie API Test Extension – Testing Cookie API

Live HTTP headers – Displays the live log with the http requests headers

JavaScript pause/resume – Pauses / resumes JavaScript execution

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.

Sep	NOV	Jan
	12
2011	2012	2013

Google Chrome Extensions

chrome.tabs

Contents

Manifest

Examples

API Reference: chrome.tabs

Types

Tab

Properties of Tab

InjectDetails

Properties of InjectDetails

Methods

executeScript

Parameters

Parameters

Callback function

get

Parameters

Parameters

Callback function

getCurrent

Parameters

Parameters

Callback function

create

Parameters

Parameters

Callback function

move

Parameters

Parameters

Callback function

update

Parameters

Parameters

Callback function

remove

Parameters

Callback function

captureVisibleTab

Parameters

Parameters

Callback function

reload

Parameters

Callback function

duplicate

Parameters

Parameters

Callback function

sendMessage

Parameters

Parameters

Callback function

connect

Parameters

insertCSS

Parameters

Callback function

highlight

Parameters

Parameters

Callback function

query

Parameters

Parameters

Callback function

detectLanguage

Parameters

Parameters

Callback function

Events

onHighlighted

Listener Parameters

onRemoved

Listener Parameters

onUpdated

Listener Parameters

onAttached

Listener Parameters