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.

[PENDING: We should show tooltips and badges, as well.]

Manifest

Register your browser action in the extension manifest like this:

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

Note: Even if you don't include any of the values, you must include an empty browser_action entry in the manifest so that the system reserves space for your browser action in the toolbar.

Parts of the UI

A browser action must have an icon. It can also have 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.

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. [PENDING: if you have a color but no text, will anything display?]

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. Then specify the HTML file in the manifest, using the popup field of browser_action.

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" and "page" icons. 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.