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
- bookmark-it
- favourite-colour
- find-across-tabs
- forget-it
- google-userinfo
- native-messaging
- open-my-page-button
- permissions
- store-collected-images
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 acanvas
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
Chrome | Edge | Firefox | Firefox for Android | Opera | |
---|---|---|---|---|---|
ColorArray | Yes | Yes | 45 | No | Yes |
ImageDataType | Yes | Yes | 45 | No | Yes |
disable | Yes | Yes | 45 | No | Yes |
enable | Yes | Yes | 45 | No | Yes |
getBadgeBackgroundColor | Yes | Yes | 45 | No | Yes |
getBadgeText | Yes | Yes | 45 | No | Yes |
getPopup | Yes | No | 45 | 57 | Yes |
getTitle | Yes | 15 | 45 | 55 | Yes |
onClicked | Yes | Yes | 45 | 55 | Yes |
openPopup | No | No | 57 | No | No |
setBadgeBackgroundColor | Yes | Yes | 45 | No | Yes |
setBadgeText | Yes | Yes | 45 * | No | Yes |
setIcon | Yes * | Yes * | 45 | No | 15 |
setPopup | Yes | Yes | 45 | 57 | Yes |
setTitle | Yes | 15 | 45 | 55 | Yes |
The "Chrome incompatibilities" section is included from https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities using the WebExtChromeCompat macro.
If you need to update this content, edit https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities, then shift-refresh this page to see your changes.
Chrome incompatibilities
None.
This API is based on Chromium's chrome.browserAction
API. This documentation is derived from browser_action.json
in the Chromium code.
// Copyright 2015 The Chromium Authors. All rights reserved. // // Redistribution and use in source and binary forms, with or without // modification, are permitted provided that the following conditions are // met: // // * Redistributions of source code must retain the above copyright // notice, this list of conditions and the following disclaimer. // * Redistributions in binary form must reproduce the above // copyright notice, this list of conditions and the following disclaimer // in the documentation and/or other materials provided with the // distribution. // * Neither the name of Google Inc. nor the names of its // contributors may be used to endorse or promote products derived from // this software without specific prior written permission. // // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.