browserAction

Add a clickable button to the browser's toolbar. You can associated a popup with the button. The popup is specified using HTML, CSS and JavaScript, just like a normal web page. JavaScript running in the popup gets access to all the same WebExtension APIs as your background scripts.

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

You can define most of a browser action's properties declaratively using the browser_action key in manifest.json, but can also redefine them programmatically using this API.

See also the section on browser actions in Anatomy of a WebExtension.

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: Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup.

	Edge	Firefox	Chrome	Opera
`ColorArray`	?	45.0	Yes	33
`ImageDataType`	?	45.0	Yes	33
`disable`	?	45.0	Yes	33
`enable`	?	45.0	Yes	33
`getBadgeBackgroundColor`	?	45.0	Yes	33
`getBadgeText`	?	45.0	Yes	33
`getPopup`	?	45.0	Yes	33
`getTitle`	?	45.0	Yes	33
`onClicked`	?	45.0	Yes	33
`openPopup`	?	45.0	Yes	33
`setBadgeBackgroundColor`	?	45.0	Yes	33
`setBadgeText`	?	45.0	Yes	33
`setIcon`	?	45.0	Yes	33
`setPopup`	?	45.0	Yes	33
`setTitle`	?	45.0	Yes	33

	Firefox
`ColorArray`	No
`ImageDataType`	No
`disable`	No
`enable`	No
`getBadgeBackgroundColor`	No
`getBadgeText`	No
`getPopup`	No
`getTitle`	No
`onClicked`	No
`openPopup`	No
`setBadgeBackgroundColor`	No
`setBadgeText`	No
`setIcon`	No
`setPopup`	No
`setTitle`	No

Chrome incompatibilities

Firefox does not support:
- openPopup()

Example add-ons

Acknowledgements

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.