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

Register your browser action in the extension manifest like this:

{
  "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.

Tooltip

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.