You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
paramName
( optional Type array of paramType )
Undocumented.
Description of this parameter from the json schema.

Google Chrome Extensions (Labs)

Tabs

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.

Two tabs in a window

Manifest

You must declare the "tabs" permission in your extension's manifest to use the tabs API. For example: 

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

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

Methods

captureVisibleTab

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

Captures the visible area of the currently selected tab in the specified window.

Parameters

windowId
( optional Type array of integer )
The target window. Defaults to the current window.
options
( optional Type array of object )
Set parameters of image capture, such as the format of the resulting image. This parameter was added in version 5.0 . Earlier versions of chrome will throw an exception unless you omit it.
format
( optional Type array of string )
The format of the resulting image. Default is jpeg.
quality
( optional Type array of 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
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(string dataUrl) {...});
dataUrl
( Type array of 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.

connect

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
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
connectInfo
( optional Type array of object )
Undocumented.
Description of this parameter from the json schema.
name
( optional Type array of string )
Will be passed into onConnect for content scripts that are listening for the connection event.

Returns

paramName
( Port array of paramType )
A port that can be used to communicate with the content scripts running in the specified tab.

Callback function

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

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

function(Type param1, Type param2) {...});

create

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

Creates a new tab.

Parameters

createProperties
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
windowId
( optional Type array of integer )
The window to create the new tab in. Defaults to the current window.
index
( optional Type array of 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 Type array of 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.
selected
( optional Type array of boolean )
Whether the tab should become the selected tab in the window. Defaults to true
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(Tab tab) {...});
tab
( Tab array of paramType )
Details about the created tab. Will contain the ID of the new tab.

detectLanguage

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

Detects the primary language of the content in a tab.

Parameters

tabId
( optional Type array of integer )
Defaults to the selected tab of the current window.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(string language) {...});
language
( Type array of 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.

executeScript

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

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

Parameters

tabId
( optional Type array of integer )
The ID of the tab in which to run the script; defaults to the selected tab of the current window.
details
( Type array of object )
Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time.
code
( optional Type array of string )
JavaScript code to execute.
file
( optional Type array of string )
JavaScript file to execute.
allFrames
( optional Type array of boolean )
If allFrames is true, this function injects script into all frames of current page. By default, it's false and script is injected only into the top main frame.
callback
( optional Type array of function )
Called after all the JavaScript has been executed.

Returns

Callback function

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

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

function() {...});

get

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

Retrieves details about the specified tab.

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(Tab tab) {...});
tab
( Tab array of paramType )
Undocumented.
Description of this parameter from the json schema.

getAllInWindow

void chrome.tabs.getAllInWindow(, integer windowId, function callback)

Gets details about all tabs in the specified window.

Parameters

windowId
( optional Type array of integer )
Defaults to the current window.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(array of Tab tabs) {...});
tabs
( Type array of Tab array of paramType paramType )
Undocumented.
Description of this parameter from the json schema.

getCurrent

void 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
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(Tab tab) {...});
tab
( optional Tab array of paramType )
Undocumented.
Description of this parameter from the json schema.

getSelected

void chrome.tabs.getSelected(, integer windowId, function callback)

Gets the tab that is selected in the specified window.

Parameters

windowId
( optional Type array of integer )
Defaults to the current window.
callback
( Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(Tab tab) {...});
tab
( Tab array of paramType )
Undocumented.
Description of this parameter from the json schema.

insertCSS

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

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

Parameters

tabId
( optional Type array of integer )
The ID of the tab in which to insert the CSS; defaults to the selected tab of the current window.
details
( Type array of object )
Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time.
code
( optional Type array of string )
CSS code to be injected.
file
( optional Type array of string )
CSS file to be injected.
allFrames
( optional Type array of boolean )
If allFrames is true, this function injects CSS text into all frames of current page. By default, it's false and CSS is injected only into the top main frame.
callback
( optional Type array of function )
Called when all the CSS has been inserted.

Returns

Callback function

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

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

function() {...});

move

void chrome.tabs.move(, integer tabId, object moveProperties, function callback)

Moves a tab 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

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
moveProperties
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
windowId
( optional Type array of integer )
Defaults to the window the tab is currently in.
index
( Type array of integer )
The position to move the window to. The provided value will be clamped to between zero and the number of tabs in the window.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(Tab tab) {...});
tab
( Tab array of paramType )
Details about the moved tab.

remove

void chrome.tabs.remove(, integer tabId, function callback)

Closes a tab.

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function() {...});

sendRequest

void chrome.tabs.sendRequest(, integer tabId, any request, function responseCallback)

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

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
request
( Type array of any )
Undocumented.
Description of this parameter from the json schema.
responseCallback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(any response) {...});
response
( Type array of any )
The JSON response object sent by the handler of the request.

update

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

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
updateProperties
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
url
( optional Type array of string )
Undocumented.
Description of this parameter from the json schema.
selected
( optional Type array of boolean )
Undocumented.
Description of this parameter from the json schema.
callback
( optional Type array of function )
Undocumented.
Description of this parameter from the json schema.

Returns

Callback function

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

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

function(Tab tab) {...});
tab
( Tab array of paramType )
Details about the updated tab.

Events

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.

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
attachInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
newWindowId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
newPosition
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

onCreated

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

Fires when a tab is created.

Parameters

tab
( Tab array of paramType )
Details of the tab that was created.

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.

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
detachInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
oldWindowId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
oldPosition
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

onMoved

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

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

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
moveInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
windowId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
fromIndex
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
toIndex
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

onRemoved

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

Fires when a tab is closed.

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.

onSelectionChanged

chrome.tabs.onSelectionChanged.addListener(function(integer tabId, object selectInfo) {...});

Fires when the selected tab in a window changes.

Parameters

tabId
( Type array of integer )
The ID of the tab that has become selected.
selectInfo
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
windowId
( Type array of integer )
The ID of the window the selected tab changed inside of.

onUpdated

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

Fires when a tab is updated.

Parameters

tabId
( Type array of integer )
Undocumented.
Description of this parameter from the json schema.
changeInfo
( Type array of object )
Lists the changes to the state of the tab that was updated.
status
( Type array of string )
The status of the tab. Can be either loading or complete.
url
( optional Type array of string )
Only specified if the tab's URL changed.
tab
( Tab array of paramType )
Gives the state of the tab that was updated.

Types

Tab

paramName
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
id
( Type array of integer )
The ID of the tab. Tab IDs are unique within a browser session.
index
( Type array of integer )
The zero-based index of the tab within its window.
windowId
( Type array of integer )
The ID of the window the tab is contained within.
selected
( Type array of boolean )
Whether the tab is selected.
url
( Type array of string )
The URL the tab is displaying.
title
( optional Type array of string )
The title of the tab. This may not be available if the tab is loading.
favIconUrl
( optional Type array of string )
The URL of the tab's favicon. This may not be available if the tab is loading.
status
( optional Type array of string )
Either loading or complete.
incognito
( Type array of boolean )
Whether the tab is in an incognito window.