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.
WARNING: This is the BETA documentation. It may not work with the stable release of Chrome.
WARNING: This is unofficial documentation. It may not work with the current release of Chrome.

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

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

Methods

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

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.

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
( integer )
Undocumented.
connectInfo
( optional object )
Undocumented.
name
( optional string )
Will be passed into onConnect for content scripts that are listening for the connection event.

Returns

( Port )
A port that can be used to communicate with the content scripts running in the specified tab. The port's onDisconnect event is fired if the tab closes or does not exist.

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

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.

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

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.

executeScript

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 integer )
The ID of the tab in which to run the script; defaults to the active tab of the current window.
details
( 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 string )
JavaScript code to execute.
file
( optional string )
JavaScript file to execute.
allFrames
( optional 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 function )
Called after all the JavaScript has been executed.

Callback function

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

function() {...};

get

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

Retrieves details about the specified tab.

Parameters

tabId
( integer )
Undocumented.
callback
( function )
Undocumented.

Callback function

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

function(Tab tab) {...};
tab
( Tab )
Undocumented.

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

Callback function

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

function(Tab tab) {...};
tab
( optional Tab )
Undocumented.

highlight

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

Highlights the given tabs.

Parameters

highlightInfo
( object )
Undocumented.
windowId
( integer )
The window that contains the tabs.
tabs
( array of integer or integer )
One or more tab indices to highlight.
callback
( function )
Undocumented.

Callback function

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

function(Window window) {...};
window
( Window )
Contains details about the window whose tabs were highlighted.

insertCSS

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 integer )
The ID of the tab in which to insert the CSS; defaults to the active tab of the current window.
details
( 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 string )
CSS code to be injected.
file
( optional string )
CSS file to be injected.
allFrames
( optional 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 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() {...};

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 )
Undocumented.
windowId
( optional integer )
Defaults to the window the tab is currently in.
index
( 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 function )
Undocumented.

Callback function

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.

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

Callback function

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

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

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 )
Undocumented.
bypassCache
( optional boolean )
Whether using any local cache. Default is false.
callback
( optional function )
Undocumented.

Callback function

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

Callback function

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

function() {...};

sendRequest

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
( integer )
Undocumented.
request
( any )
Undocumented.
responseCallback
( optional function )
Undocumented.
Parameters
response
( any )
The JSON response object sent by the handler of the request. 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 callback 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 request. 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.

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

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.

Events

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 )
Undocumented.
tabId
( integer )
The ID of the tab that has become active.
windowId
( integer )
The ID of the window the active tab changed inside of.

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 )
Undocumented.
attachInfo
( object )
Undocumented.
newWindowId
( integer )
Undocumented.
newPosition
( integer )
Undocumented.

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.

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 )
Undocumented.
detachInfo
( object )
Undocumented.
oldWindowId
( integer )
Undocumented.
oldPosition
( integer )
Undocumented.

onHighlighted

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

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

Listener parameters

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

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 )
Undocumented.
moveInfo
( object )
Undocumented.
windowId
( integer )
Undocumented.
fromIndex
( integer )
Undocumented.
toIndex
( integer )
Undocumented.

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 )
Undocumented.
removeInfo
( object )
Undocumented.
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 )
Undocumented.
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.

Types

Tab

( object )
Undocumented.
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
( string )
The URL the tab is displaying.
title
( optional string )
The title of the tab. This may not be available if the tab is loading.
favIconUrl
( optional string )
The URL of the tab's favicon. This may not be available if the tab is loading.
status
( optional string )
Either loading or complete.
incognito
( boolean )
Whether the tab is in an incognito window.