User interface components

This article is an overview of the components you can use to build a WebExtension's user interface.

Browser actions

A browser action is a button you can add to the browser toolbar. Users can click the button to interact with your add-on.

There are two ways to specify a browser action: with a popup, or without a popup.

If you don't specify a popup, then when the user clicks the button an event is dispatched to the add-on, which you can listen for using browserAction.onClicked:

chrome.browserAction.onClicked.addListener(handleClick);

If you do specify a popup, the click event is not dispatched: instead, the popup will be shown when the user clicks the button. The user will be able to interact with the popup and it will close automatically when the user clicks outside it.

Note that your extension can have only one browser action.

Specifying the browser action

You define the browser action's properties - icon, title, popup - using the browser_action key in manifest.json:

"browser_action": {
  "default_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

The only mandatory key is default_icon. You can change any of these properties programmatically using the browserAction API.

Examples

The webextensions-examples repo on GitHub contains several examples of WebExtensions that use browser actions:

• bookmark-it uses a browser action without a popup
• beastify uses a browser action with a popup

Page actions

Page actions are like browser actions in most respects, except that:

• browser actions are displayed all the time, and are for actions that are applicable more or less all the time
• page actions are for actions which only make sense on certain pages, and are only displayed when those tabs are active.

To emphasise that page actions are closely tied to particular pages, they're shown inside the address bar, rather than the main toolbar:

Unlike browser actions, they're hidden by default, and you call pageAction.show() and pageAction.hide() to show or hide them in specific tabs.

Specifying the page action

You define the page action's properties - icon, title, popup - using the page_action key in manifest.json:

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

The only mandatory key is default_icon. You can change any of these properties programmatically, and show/hide the page action, using the pageAction API.

Examples

The chill-out example WebExtension uses a page action.

Popups

A popup is a dialog that's associated with a browser action or a page action.

When the user clicks the action's icon, the popup is shown. When the user clicks anywhere outside the popup, the popup is closed. To close the popup programmatically, call window.close() from a script running in the popup.

The popup is specified as an HTML file, which can include CSS and JavaScript files, just like a normal web page. Unlike a normal page, though, the JavaScript can use all the WebExtension APIs that the extension has permissions for.

You can ask the browser to include a stylesheet in your popup that will make it look consistent with the browser's UI. To do this, include "browser_style": true in your browser_action or page_action key.

Popups have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of eval(). See Content Security Policy for more details on this.

You can debug a popup's markup and JavaScript using the Add-on Debugger, but you'll need to tweak a setting to stop the popup from auto-hiding. Read about debugging popups.

Popup resizing

Popups resize automatically to fit their content. The algorithm for this may differ from one browser to another.

In Firefox, the size is calculated just before the popup is shown, and at most 10 times per second after DOM mutations. For strict mode documents, the size is calculated based on the layout size of the <body> element. For quirks mode, it's the <html> element. Firefox calculates the preferred width of the contents of that element, reflows it to that width, and then resizes so there's no vertical scrolling. It will at most grow to a size of 800x600px if that fits on the user's screen. If the user has moved the popup's associated action to the menu's panel, then the popup appears inside the menu's panel and is given a fixed width.

Options pages

Options pages enable you to define preferences for your WebExtension that your users can change. Users can access the options page for an add-on from the browser's add-ons manager:

The way users access the page, and the way it is integrated into the browser's user interface, will vary from one browser to another.

You can open the page programmatically by calling runtime.openOptionsPage().

Options pages have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of eval(). See Content Security Policy for more details on this.

Specifying the options page

To create an options page:

• write an HTML file defining the page. This file can include CSS and JavaScript files, just like a normal web page. JavaScript running in the page can can use all the WebExtension APIs that the add-on has permissions for. In particular, you can use the storage API to persist preferences.
• package these files in your add-on
• include an options_ui key in manifest.json, giving it the URL to the page.

Examples

The favourite-colour example WebExtension uses an options page.

Context menu items

Using the contextMenus API, you can add items to the browser's context menu, to be displayed in the contexts you specify. For example, you can show the item only when the user clicks on an image, or on an editable element, or when part of a page is selected.

Specifying context menu items

You manage context menu items programmatically, using the contextMenus API.

Examples

The context-menu-demo WebExtension creates various different sorts of context menu items.

Notifications

Using the notifications API, you can create transient notifications, using the underlying operating system's notification service:

Specifying notifications

You manage notifications programmatically, using the notifications API.

Examples

The notify-link-clicks-i18n WebExtension creates notifications.