browserAction

By adding a clickable button to the browser's toolbar, you can associate a popup with the button. As with a web page, popup is specified using HTML, CSS and JavaScript. Any JavaScript running in the popup, gets access to the same WebExtension APIs as your background scripts.

If you specify a popup, when the user clicks the icon, the popup will show and its content loaded. If you do not specify a popup, when the user clicks the icon, an event is dispatched to your extension.

You can decleratively define most browser action properties using the browser_action key in manifest.json, and redefining them programmatically using this API.

Also see browser actions in Anatomy of a WebExtension.

Styleguide

You use browser actions to place a button in the main Mozilla Firefox toolbar. The default is for this button to be placed to the right of the address bar. The user is free to move this button to multiple locations in the browser.

Button

A browser action button is represented with an icon. Its states are defined by Firefox, and are matched to the operating system. Aside from those states, a button can be highlighted to indicate important events.

Do not use additional indicators to hint that the button opens a panel, instead of performing an action. As most buttons open panels, having an additional indicator will clutter the interface.

Icon

The icon should be clear and distinguishable in one color. To keep a clean appearance within Firefox and match individual OSs we will color the svg provided in the same color as other toolbar icons. The icon should be 16×16px outline svg (see example).

To clearly identify your add-on, make sure to design an icon that is unique to your add-on.

If the user moves the button to other locations the icon will be scaled accordingly.

Sizes
URL Bar 12×12 px
Toolbar 16×16 px
Menu Panel 32×32 px
Display Icon 64×64 px

States

Browser actions as buttons have different appearances indicating their state.

enabled

Basic state of a button if it’s function is available.

disabled

Basic state of a button if it’s function is not available.

Should not be needed on a browserAction as they should work all the time. If it does not, consider if it should be a page action instead.

highlighted (unique to Firefox)

To indicate an important active state of a browser action, you can set it to be highlighted. This will color the icon blue, until the state is resolved.

Can only be used if the icon is provided as an .svg file.

Locations

A browser action by default is placed in the toolbar to the right of the address bar. The user can however move it to any other location in the toolbar, the bookmark toolbar, the tab-bar, or the menu panel.

In the menu panel, the content specified to be displayed in the popup will be displayed in a sub-panel of the menu. Prepare your add-on to deal with the changed appearance, if placed in the menu panel.

Tooltip

Users should be able to understand what will happen when they click the button. Therefore the tooltip should describe what the button does by clearly stating the action which will be performed on click.

Do not just put the name of the add-on in the tooltip! Be very descriptive of the action the button will perform.

Do not use the tooltip for any other form of information, like elaborate statistics of your add-on. Keep it simple so that the users can easily understand what will happen if they click the button.

Badge

Use sparingly to inform users about important events. Do not use them to constantly provide status updates.

The text can be up to 4 characters, and will not extend beyond the borders of the button.

We recommend using one of the following 3 states, for different severity of notifications:

Casual 2EA3FF to #0996F8 (blue gradient)
Warning #EE4B36 to #D92215 (red gradient)
Update #70CF5B to #57BD35 (green gradient)

For compatibility with Chrome/Opera we will also support free color selection, but recommend using Firefox defaults to maintain consistency.

Panel

Use panels if your browser action provides the user with multiple actions, or displays another form of content on request. Be sure to align the content of the panel using our style recommendations.

More info on how to build your panel can be found in Style Guide - Components - Panels.

Context Menu

Do not block or replace the context menu. If necessary, extend the context menu with functions needed for your add-on. Users should be able to find the same functionality they have learned to expect. For the context menu, this is used control over features and their placement.

For example, add quick access to your add-ons options, add an alternative action to the default on-click actions.

Tips

For the best visual impact, follow these guidelines:

  • Use browser actions for features that make sense on most pages.
  • Don't use browser actions for features that make sense on only a few pages.
  • Use page actions instead.
  • Use svg icons which blend well with the other icons already in Firefox.

Example extensions

Types

browserAction.ColorArray
An array of four integers in the range 0-255 defining an RGBA color.
browserAction.ImageDataType
Pixel data for an image. Must be an ImageData object (for example, from a canvas element).

Functions

browserAction.setTitle()
Sets the browser action's title. This will be displayed in a tooltip.
browserAction.getTitle()
Gets the browser action's title.
browserAction.setIcon()
Sets the browser action's icon.
browserAction.setPopup()
Sets the HTML document to be opened as a popup, when the user clicks on the browser action's icon.
browserAction.getPopup()
Gets the HTML document set as the browser action's popup.
browserAction.setBadgeText()
Sets the browser action's badge text. The badge is displayed on top of the icon.
browserAction.getBadgeText()
Gets the browser action's badge text.
browserAction.setBadgeBackgroundColor()
Sets the badge's background color.
browserAction.getBadgeBackgroundColor()
Gets the badge's background color.
browserAction.enable()
Enables the browser action for a tab. By default, browser actions are enabled.
browserAction.disable()
Disables the browser action for a tab.
browserAction.openPopup()
Opens the extension popup window in the active window, but does not grant tab permissions.

Events

browserAction.onClicked
Fires when a browser action icon is clicked. This event will not activate if the browser action has a popup.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
ColorArray Yes Yes45 No Yes
ImageDataType Yes Yes45 No Yes
disable Yes Yes45 No Yes
enable Yes Yes45 No Yes
getBadgeBackgroundColor Yes Yes45 No Yes
getBadgeText Yes Yes45 No Yes
getPopup Yes No4557 Yes
getTitle Yes154555 Yes
onClicked Yes Yes4555 Yes
openPopup No No57 No No
setBadgeBackgroundColor Yes Yes45 No Yes
setBadgeText Yes Yes45 * No Yes
setIcon Yes * Yes *45 No15
setPopup Yes Yes4557 Yes
setTitle Yes154555 Yes

Chrome incompatibilities

None.

Acknowledgements

This API is based on Chromium's chrome.browserAction API. This documentation is derived from browser_action.json in the Chromium code.

Document Tags and Contributors

 Contributors to this page: bunnybooboo, PushpitaPikuDey, bram
 Last updated by: bunnybooboo,