page_action

Type Object
Mandatory No
Example 
"page_action": {
  "browser_style": true,
  "default_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

A page action is an icon that your extension adds inside the browser's URL bar.

Your extension may optionally also supply an associated 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 icon, 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 icon.

You can also create and manipulate page actions programmatically using the pageAction API.

Page actions are like browser actions, except that they are associated with particular web pages rather than with the browser as a whole. If an action is only relevant on certain pages, then you should use a page action and display it only on relevant pages. If an action is relevant to all pages or to the browser itself, use a browser action.

While browser actions are displayed by default, page actions are hidden by default. They can be shown for a particular tab by calling pageAction.show() , passing in the tab's id. You can also change this default behavior using the show_matches property.

Syntax

The page_action key is an object that may have any of three properties, all optional:

Name Type Description
browser_style Boolean

Optional. Defaults to false.

Use this to include a stylesheet in your popup that will make it look consistent with the browser's UI and with other extensions that use the browser_style property. Although this key defaults to false, it's recommended that you include it and set it to true in order to make your popups consistent with the look of the rest of the browser user interface.

In Firefox, the stylesheet can be seen at chrome://browser/content/extension.css, or chrome://browser/content/extension-mac.css on macOS.

The Firefox Style Guide describes the classes you can apply to elements in the popup in order to get particular styles.

The latest-download example extension uses browser_style in its popup.
default_icon Object or String

Use this to specify an icon for the action.

It's recommended that you supply two icons here (19×19 pixels and 38×38 pixels), and specify them in an object with properties named "19" and "38", like this:

    "default_icon": {
      "19": "geo-19.png",
      "38": "geo-38.png"
    }

If you do this, then the browser will pick the right size icon for the screen's pixel density.

You can just supply a string here:

"default_icon": "geo.png"

If you do this, then the icon will be scaled to fit the toolbar, and may appear blurry.
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 <link> and <script> elements, just like a normal web page. However, don't use <script> with embedded code, because you'll get a Content Violation Policy error. Instead, <script> must use the src attribute to load a separate script file.

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 icon, displayed when the user moves their mouse over it.

This is a localizable property.
hide_matches Array of Match Pattern except <all_urls>

Hide the page action by default for pages whose URLs match any of the given match patterns.

Note that page actions are always hidden by default unless show_matches is given. Therefore, it only makes sense to include this property if show_matches is also given, and will override the patterns in show_matches.

For example, consider a value like:

"page_action": {
  "show_matches": ["https://*.mozilla.org/*"],
  "hide_matches": ["https://developer.mozilla.org/*"]
}

This shows the page action by default for all HTTPS URLs under the "mozilla.org" domain, except for pages under "developer.mozilla.org".
show_matches Array of Match Pattern

Show the page action by default for pages whose URLs match any of the given patterns.

See also hide_matches.
pinned Boolean

Optional. Defaults to true.

Controls whether or not the page action should appear in the location bar by default when the user installs the extension. This property is no longer supported since Firefox 89.

Example

"page_action": {
  "default_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  }
}

A page 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.pageAction.onClicked.addListener(handleClick);
"page_action": {
  "default_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

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

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
page_action
Yes
If an extension defines a page action, it is not allowed to define a browser action as well.
49
Since Chrome 49, page actions are displayed on the toolbar, rather than in the address bar.
14
48
?
Yes
If an extension defines a page action, it is not allowed to define a browser action as well.
14
If an extension defines a page action, it is not allowed to define a browser action as well.
?
?
Yes
?
?
?
browser_style
No
No
48
?
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.
?
?
Yes
?
?
?
default_popup
Yes
14
48
?
Yes
14
?
?
Yes
?
?
?
default_title
Yes
14
48
?
Yes
14
?
?
Yes
?
?
?
hide_matches
No
No
59
?
No
No
?
?
59
?
?
?
pinned
No
No
64
?
No
No
?
?
No
?
?
?
show_matches
No
No
59
?
No
No
?
?
79
?
?
?

See also

© 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/page_action