page_action

Syntax

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

browser_style Optional

Boolean. Defaults to false.

Warning: Do not set browser_style to true: it's not supported in Manifest V3, starting from Firefox 118. See Manifest V3 migration for browser_style.

In Firefox, the stylesheet can be seen at chrome://browser/content/extension.css or chrome://browser/content/extension-mac.css on macOS. The latest-download example extension uses browser_style in its popup.

default_icon Optional

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:

json

"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:

json

"default_icon": "geo.png"

If you do this, then the icon will be scaled to fit the toolbar, and may appear blurry.

You can use an SVG icon. You can also have the icon adapt to light and dark themes using a media query on prefers-color-scheme. For example:

css

#outside {
  fill: black;
}
#inside {
  fill: red;
}
@media (prefers-color-scheme: dark) {
  #outside {
    fill: white;
  }
  #inside {
    fill: black;
  }
}

For more information, see the themed-icons example.

Note: An implicit CSS filter applies to SVG icons in dark UI themes. This filter will be deactivated in Firefox Desktop version 152 (Firefox bug 2016509). You can test SVG icons with the CSS filter disabled by creating a boolean about:config preference called extensions.webextensions.pageActionIconDarkModeFilter.enabled and setting it to false. The filter is deactivated by default in Firefox Desktop Nightly from 149.

default_popup Optional

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 to the extension having the appropriate permissions). This is a localizable property.

default_title Optional

String. Tooltip for the icon, displayed when the user moves their mouse over it. This is a localizable property.

hide_matches Optional

Array of MatchPattern 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:

json

"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 Optional

Array of MatchPattern. Show the page action by default for pages whose URLs match any of the given patterns. See also hide_matches.

pinned Optional

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

See also

• browser_action
• sidebar_action
• Browser styles