Type | Object |
---|---|
Mandatory | No |
Example | "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", "theme_icons": [{ "light": "icons/geo-16-light.png", "dark": "icons/geo-16.png", "size": 16 }, { "light": "icons/geo-32-light.png", "dark": "icons/geo-32.png", "size": 32 }] } |
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.
The browser_action
key is an object that may have any of the following properties, all optional:
Name | Type | Description |
---|---|---|
browser_style | Boolean | Optional, defaulting to Use this to include a stylesheet in your popup that will make its look consistent with the browser's UI and with other extensions that use the In Firefox, the stylesheet can be seen at chrome://browser/content/extension.css, or chrome://browser/content/extension-mac.css on OS X. When setting dimensions, be aware that this style sheet currently sets Browser styles describes the classes you can apply to elements in the popup in order to get particular styles. The latest-download example extension uses Note: Setting
|
default_area | String | Defines the part of the browser in which the button is initially placed. This is a string that may take one of four values:
This property is only supported in Firefox. This property is optional, and defaults to "navbar". Firefox remembers the An extension can't change the location of the button after it has been installed, but the user may be able to move the button using the browser's built-in UI customization mechanism. |
default_icon |
Object or String
| Use this to specify one or more icons for the browser action. The icon is shown in the browser toolbar by default. Icons are specified as URLs relative to the manifest.json file itself. You can specify a single icon file by supplying a string here: "default_icon": "path/to/geo.svg" To specify multiple icons in different sizes, specify an object here. The name of each property is the icon's height in pixels, and must be convertible to an integer. The value is the URL. For example: "default_icon": { "16": "path/to/geo-16.png", "32": "path/to/geo-32.png" } You cannot specify multiple icons of the same sizes. |
default_popup | String | The path to an HTML file containing the specification of the popup. The HTML file may include CSS and JavaScript files using Unlike a normal web page, JavaScript running in the popup can access all the WebExtension APIs (subject, of course, to the extension having the appropriate permissions). This is a localizable property. |
default_title | String | Tooltip for the button, displayed when the user moves their mouse over it. If the button is added to the browser's menu panel, this is also shown under the app icon. This is a localizable property. |
theme_icons | Array | This property enables you to specify different icons for themes depending on whether Firefox detects that the theme uses dark or light text. If this property is present, it's an array containing at least one
Icons are specified as URLs relative to the manifest.json file. You should supply 16x16 and 32x32 (for retina display) |
The browser action's icon may need to be displayed in different sizes in different contexts:
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:
window.devicePixelRatio
.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" }
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.
"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:
browser.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.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
browser_action |
Yes
If an extension defines a browser action, it is not allowed to define a page action as well.
|
14 |
48 |
? |
Yes
If an extension defines a browser action, it is not allowed to define a page action as well.
|
14
If an extension defines a browser action, it is not allowed to define a page action as well.
|
? |
? |
55 |
? |
? |
? |
browser_style |
No |
No |
48 |
? |
No |
No |
? |
? |
No |
? |
? |
? |
default_area |
No |
No |
54 |
? |
No |
No |
? |
? |
No |
? |
? |
? |
default_icon |
Yes
SVG icons are not supported.
|
14
["SVG icons are not supported.", "'default_icon' must be an object, with explicit sizes."]
|
48 |
? |
Yes
SVG icons are not supported.
|
14
SVG icons are not supported. Grayscale images will be treated as template icons and processed with the system accent color and system appearance.
|
? |
? |
No |
? |
? |
? |
default_popup |
Yes |
14 |
48 |
? |
Yes |
14 |
? |
? |
57 |
? |
? |
? |
default_title |
Yes |
14 |
48 |
? |
Yes |
14 |
? |
? |
55
Browser actions are presented as menu items, and the title is the menu item's label.
|
? |
? |
? |
theme_icons |
No |
No |
56 |
? |
No |
No |
? |
? |
No |
? |
? |
? |
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action