chrome.browserAction

Manifest
Parts of the UI
1. Icon
2. Tooltip
3. Badge
4. Popup
Tips
Examples
API reference: chrome.browserAction
1. Types
  1. ColorArray
  2. ImageDataType
2. Methods
  1. setTitle
  2. getTitle
  3. setIcon
  4. setPopup
  5. getPopup
  6. setBadgeText
  7. getBadgeText
  8. setBadgeBackgroundColor
  9. getBadgeBackgroundColor
  10. enable
  11. disable
3. Events
  1. onClicked
4. Sample Extensions

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.

Manifest

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

If you only provide one of the 19px or 38px icon size, the extension system will scale the icon you provide to the pixel density of the user's display, which can lose detail or make it look fuzzy. The old syntax for registering the default icon is still supported:

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon19.png"  // optional
    // equivalent to "default_icon": { "19": "images/icon19.png" }
  },
  ...
}

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 dips (device-independent pixels) wide and high. Larger icons are resized to fit, but for best results, use a 19-dip 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 properly display icon when screen pixel density (ratio size_in_pixel / size_in_dip) is different than 1, the icon can be defined as set of images with different sizes. The actual image to display will be selected from the set to best fit the pixel size of 19 dip icon. At the moment, the icon set can contain images with pixel sizes 19 and 38.

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 )

ImageDataType

( imagedata )

Pixel data for an image. Must be an ImageData object (for example, from a canvas element).

Methods

setTitle

chrome.browserAction.setTitle(object details)

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

Parameters

details ( object )

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

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 )

result ( string )

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, or as dictionary of either one of those. Either the path or the imageData property must be specified.

Parameters

details ( object )

imageData ( optional ImageDataType or object ): Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then image with size scale * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'19': foo}'
path ( optional string or object ): Either a relative image path or a dictionary {size -> relative image path} pointing to icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then image with size scale * 19 will be selected. Initially only scales 1 and 2 will be supported. At least one image must be specified. Note that 'details.path = foo' is equivalent to 'details.imageData = {'19': foo}'
tabId ( optional integer ): Limits the change to when a particular tab is selected. Automatically resets when the tab is closed.

callback ( optional function )

Callback function

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

function() {...};

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.

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 )

result ( string )

Callback function

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

function(string result) {...};

result ( string )

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.

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 )

result ( string )

Callback function

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

function(string result) {...};

result ( string )

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.

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 )

result ( ColorArray )

Callback function

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

function(ColorArray result) {...};

result ( ColorArray )

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.

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.

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 –

Google Chrome Extensions

chrome.browserAction

Contents

Manifest

Parts of the UI

Icon

Tooltip

Badge

Popup

Tips

Examples

API Reference: chrome.browserAction

Types

ColorArray

ImageDataType

Methods

setTitle

Parameters

getTitle

Parameters

Parameters

Callback function

setIcon

Parameters

Callback function

setPopup

Parameters

getPopup

Parameters

Parameters

Callback function

setBadgeText

Parameters

getBadgeText

Parameters

Parameters

Callback function

setBadgeBackgroundColor

Parameters

getBadgeBackgroundColor

Parameters

Parameters

Callback function

enable

Parameters

disable

Parameters

Events

onClicked

Listener Parameters

Sample Extensions that use chrome.browserAction