action

Syntax

The action key is an object that may have any of these properties, all optional:

browser_style Optional Deprecated

Boolean. Optional, defaulting to false.

Warning: Do not set browser_style to true: its support in Manifest V3 was removed in Firefox 118. See Manifest V3 migration for browser_style.

default_area Optional

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:

• "navbar": the button is placed in the main browser toolbar, alongside the URL bar.
• "menupanel": the button is placed in a popup panel.
• "tabstrip": the button is placed in the toolbar that contains browser tabs.
• "personaltoolbar": the button is placed in the bookmarks toolbar.

This property is only supported in Firefox. This property is optional, and defaults to "menupanel". Firefox remembers the default_area setting for an extension, even if that extension is uninstalled and subsequently reinstalled. To force the browser to acknowledge a new value for default_area, the id of the extension must be changed. 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 Optional

Object or String. Use this to specify one or more icons for the 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:

json

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

json

"default_icon": {
  "16": "path/to/geo-16.png",
  "32": "path/to/geo-32.png"
}

You cannot specify multiple icons of the same sizes. See Choosing icon sizes for more guidance on this.

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, <script> must have a src attribute to load a file. Don't use <script> with embedded code, because you'll get a confusing Content Violation Policy error. 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 Optional

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 Optional

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 ThemeIcons object. A ThemeIcons object contains three mandatory properties:

"dark"

A URL pointing to an icon. This icon displays when a theme using dark text is active (such as the Firefox Light theme and, if no default_icon is specified, the Default theme).

"light"

A URL pointing to an icon. This icon displays when a theme using light text is active (such as the Firefox Dark theme).

"size"

The size of the two icons in pixels.

Icons are specified as URLs relative to the manifest.json file. You should supply 16x16 and 32x32 (for retina display) ThemeIcons.

Note: Alternatively, you can specify an SVG icon in default_icon and use a media query on prefers-color-scheme to update the icon for light and dark themes. For example:

html

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

For more information, see the themed-icons example.

Choosing icon sizes

The action's icon may need to be displayed in different sizes in different contexts:

• The icon is displayed in the browser toolbar. Older versions of Firefox supported the option of placing the icon in the browser's menu panel (the panel that opens when the user clicks the "hamburger" icon). In those versions of Firefox, the menu panel icon was larger than the toolbar icon.
• On a high-density display like a Retina screen, icons needs to be twice as big.

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:

• The default height and width for icons in the toolbar is 16 * window.devicePixelRatio.
• The default height and width for icons in the menu panel is 32 * 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.

Example

"action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

An action with just an icon, specified in 2 sizes. The extension's background scripts can receive click events when the user clicks the icon using code like this:

browser.action.onClicked.addListener(handleClick);

"action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

An action with an icon, a title, and a popup. The popup is shown when the user clicks the button.

Browser compatibility