chrome.browserAction

Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its icon, a browser action can also have a tooltip, a badge, and a popup.

In the following figure, the multicolored square to the right of the address bar is the icon for a browser action. A popup is below the icon.

If you want to create an icon that isn't always visible, use a page action instead of a browser action.

Note: Packaged apps cannot use browser actions.

Manifest

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": "images/icon19.png", // optional
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

Parts of the UI

A browser action can have an icon, a tooltip, a badge, and a popup.

Icon

Browser action icons can be up to 19 pixels wide and high. Larger icons are resized to fit, but for best results, use a 19-pixel square icon.

You can set the icon in two ways: using a static image or using the HTML5 canvas element. Using static images is easier for simple applications, but you can create more dynamic UIs — such as smooth animation — using the canvas element.

Static images can be in any format WebKit can display, including BMP, GIF, ICO, JPEG, or PNG.

To set the icon, use the default_icon field of browser_action in the manifest, or call the setIcon() method.

To set the tooltip, use the default_title field of browser_action in the manifest, or call the setTitle() method. You can specify locale-specific strings for the default_title field; see Internationalization for details.

Badge

Browser actions can optionally display a badge — a bit of text that is layered over the icon. Badges make it easy to update the browser action to display a small amount of information about the state of the extension.

Because the badge has limited space, it should have 4 characters or less.

Set the text and color of the badge using setBadgeText() and setBadgeBackgroundColor(), respectively.

Popup

If a browser action has a popup, the popup appears when the user clicks the icon. The popup can contain any HTML contents that you like, and it's automatically sized to fit its contents.

To add a popup to your browser action, create an HTML file with the popup's contents. Specify the HTML file in the default_popup field of browser_action in the manifest, or call the setPopup() method.

Tips

For the best visual impact, follow these guidelines:

Do use browser actions for features that make sense on most pages.
Don't use browser actions for features that make sense for only a few pages. Use page actions instead.
Do use big, colorful icons that make the most of the 19x19-pixel space. Browser action icons should seem a little bigger and heavier than page action icons.
Don't attempt to mimic Google Chrome's monochrome "wrench" icon. That doesn't work well with themes, and anyway, extensions should stand out a little.
Do use alpha transparency to add soft edges to your icon. Because many people use themes, your icon should look nice on a variety of background colors.
Don't constantly animate your icon. That's just annoying.

Examples

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

API Reference: chrome.browserAction

Types

ColorArray

( array of integer )

Methods

enable

chrome.browserAction.enable(integer tabId)

Enables the browser action for a tab. By default, browser actions are enabled.

Parameters

tabId ( optional integer ): The id of the tab for which you want to modify the browser action.

setBadgeBackgroundColor

chrome.browserAction.setBadgeBackgroundColor(object details)

Sets the background color for the badge.

Parameters

details ( object )

color ( ColorArray or string ): An array of four integers in the range [0,255] that make up the RGBA color of the badge. For example, opaque red is [255, 0, 0, 255]. Can also be a string with a CSS value, with opaque red being #FF0000 or #F00.
tabId ( optional integer ): Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

setBadgeText

chrome.browserAction.setBadgeText(object details)

Sets the badge text for the browser action. The badge is displayed on top of the icon.

Parameters

details ( object )

text ( string ): Any number of characters can be passed, but only about four can fit in the space.
tabId ( optional integer ): Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

setTitle

chrome.browserAction.setTitle(object details)

Sets the title of the browser action. This shows up in the tooltip.

Parameters

details ( object )

tabId ( optional integer ): Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.
title ( string ): The string the browser action should display when moused over.

getBadgeText

chrome.browserAction.getBadgeText(object details, function callback)

Gets the badge text of the browser action. If no tab is specified, the non-tab-specific badge text is returned.

Parameters

details ( object )

tabId ( optional integer ): Specify the tab to get the badge text from. If no tab is specified, the non-tab-specific badge text is returned.

callback ( function )

Callback function

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

function(string result) {...};

result ( string )

setPopup

chrome.browserAction.setPopup(object details)

Sets the html document to be opened as a popup when the user clicks on the browser action's icon.

Parameters

details ( object )

tabId ( optional integer ): Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.
popup ( string ): The html file to show in a popup. If set to the empty string (''), no popup is shown.

disable

chrome.browserAction.disable(integer tabId)

Disables the browser action for a tab.

Parameters

tabId ( optional integer ): The id of the tab for which you want to modify the browser action.

getTitle

chrome.browserAction.getTitle(object details, function callback)

Gets the title of the browser action.

Parameters

details ( object )

tabId ( optional integer ): Specify the tab to get the title from. If no tab is specified, the non-tab-specific title is returned.

callback ( function )

Callback function

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

function(string result) {...};

result ( string )

getBadgeBackgroundColor

chrome.browserAction.getBadgeBackgroundColor(object details, function callback)

Gets the background color of the browser action.

Parameters

details ( object )

tabId ( optional integer ): Specify the tab to get the badge background color from. If no tab is specified, the non-tab-specific badge background color is returned.

callback ( function )

Callback function

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

function(ColorArray result) {...};

result ( ColorArray )

getPopup

chrome.browserAction.getPopup(object details, function callback)

Gets the html document set as the popup for this browser action.

Parameters

details ( object )

tabId ( optional integer ): Specify the tab to get the popup from. If no tab is specified, the non-tab-specific popup is returned.

callback ( function )

Callback function

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

function(string result) {...};

result ( string )

setIcon

chrome.browserAction.setIcon(object details, function callback)

Sets the icon for the browser action. The icon can be specified either as the path to an image file or as the pixel data from a canvas element. Either the path or the imageData property must be specified.

Parameters

details ( object )

path ( optional string ): Relative path to an image in the extension to show in the browser action.
tabId ( optional integer ): Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.
imageData ( optional imagedata ): Pixel data for an image. Must be an ImageData object (for example, from a canvas element).

callback ( optional function )

Callback function

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

function() {...};

Events

onClicked

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

Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.

Listener Parameters

tab ( tabs.Tab )

Sample Extensions that use chrome.browserAction

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

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

A browser action which changes its icon when clicked. –

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

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

CLD – Displays the language of a tab

Idle - Simple Example – Demonstrates the Idle API

Speech Recognizer – Recognizes your speech and tells you the most likely result.

Tab Inspector – Utility for working with the extension tabs api

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

Chromium Buildbot Monitor – Displays the status of the Chromium buildbot in the toolbar. Click to see more detailed status in a popup.

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.

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.

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

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

Proxy Extension API Sample – Set Chrome-specific proxies; a demonstration of Chrome's Proxy API

Speak Selection – Speaks the current selection out loud.

Talking Alarm Clock – A clock with two configurable alarms that will play a sound and speak a phrase of your choice.

Sandboxed Frame –

Aug	OCT	Jan
	05
2011	2012	2013

Google Chrome Extensions

chrome.browserAction

Contents

Manifest

Parts of the UI

Icon

Tooltip

Badge

Popup

Tips

Examples

API Reference: chrome.browserAction

Types

ColorArray

Methods

enable

Parameters

setBadgeBackgroundColor

Parameters

setBadgeText

Parameters

setTitle

Parameters

getBadgeText

Parameters

Callback function

setPopup

Parameters

disable

Parameters

getTitle

Parameters

Callback function

getBadgeBackgroundColor

Parameters

Callback function

getPopup

Parameters

Callback function

setIcon

Parameters

Callback function

Events

onClicked

Listener Parameters

Sample Extensions that use chrome.browserAction