browser_action

"browser_action": {
  "browser_style": true,
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

A browser action is a button that your extension adds to the browser's toolbar. The button has an icon, and may optionally have a popup whose content is specified using HTML, CSS, and JavaScript.

If you supply a popup, then the popup is opened when the user clicks the button, and your JavaScript running in the popup can handle the user's interaction with it. If you don't supply a popup, then a click event is dispatched to your extension's background scripts when the user clicks the button.

You can also create and manipulate browser actions programmatically using the browserAction API.

Syntax

The browser_action key is an object that may have any of the following properties, all optional:

"default_icon": "path/to/geo.svg"

    "default_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }

Choosing icon sizes

The browser action's icon may need to be displayed in different sizes in different contexts:

• The icon is displayed by default in the browser toolbar, but the user can move it into the browser's menu panel (the panel that opens when the user clicks the "hamburger" icon). The icon in the toolbar is smaller than the icon in the menu panel.
• On a high-density display like a Retina screen, icons needs to be twice as big.

If the browser can't find an icon of the right size in a given situation, it will pick the best match and scale it. Scaling may make the icon appear blurry, so it's important to choose icon sizes carefully.

There are two main approaches to this. You can supply a single icon as an SVG file, and it will be scaled correctly:

"default_icon": "path/to/geo.svg"

Alternatively, you can supply several icons in different sizes, and the browser will pick the best match.

In Firefox:

• The default height and width for icons in the toolbar is 16 * window.devicePixelRatio.
• The default height and width for icons in the menu panel is 32 * window.devicePixelRatio.

So you can specify icons that match exactly, on both normal and Retina displays, by supplying three icon files, and specifying them like this:

    "default_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png",
      "64": "path/to/geo-64.png"
    }

In Chrome, the default height and width is 19 * window.devicePixelRatio. So to get an exact match on Firefox and Chrome, Retina and non-Retina:

    "default_icon": {
      "16": "path/to/geo-16.png",
      "19": "path/to/geo-19.png",
      "32": "path/to/geo-32.png",
      "38": "path/to/geo-38.png",
      "64": "path/to/geo-64.png"
    }

If Firefox can't find an exact match for the size it wants, then it will pick the smallest icon specified that's bigger than the ideal size. If all icons are smaller than the ideal size, it will pick the biggest icon specified.

Chrome incompatibilities

Example

"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

A browser action with just an icon, specified in 2 different sizes. The extension's background scripts can receive click events when the user clicks the icon using code like this:

 chrome.browserAction.onClicked.addListener(handleClick);

"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

A browser action with an icon, a title, and a popup. The popup will be shown when the user clicks the button.

For a simple, but complete, extension that uses a browser action, see the walkthrough tutorial.