User actions

Some WebExtension APIs perform functions that are generally performed as a result of a user action. For example:

  • a browser action with a popup will display the popup when the user clicks it, but there's also a browserAction.openPopup API enabling an extension to open the popup programmatically.
  • if an extension adds a sidebar, it is typically opened by the user via some part of the browser's built-in user interface, such as the View/Sidebar menu. But there's also a sidebarAction.open API enabling an extension to open their sidebar programmatically.

To follow the principle of "no surprises", APIs like this can only be called from inside the handler for a user action. User actions include the following:

  • Clicking the extension's browser action or page action.
  • Selecting a context menu item defined by the extension.
  • Activating a keyboard shortcut defined by the extension (this only treated as a user action from Firefox 63 onwards).
  • Clicking a button in a page bundled with the extension.

For example:

js

function handleClick() {
  browser.sidebarAction.open();
}

browser.browserAction.onClicked.addListener(handleClick);

Note that user actions in normal web pages are not treated as user actions for this purpose. For example, if a user clicks a button in a normal web page, and a content script has added a click handler for that button and in that handler sends a message to the extension's background page, then the background page message handler is not considered to be handling a user action.

Also, if a user input handler waits on a promise, then its status as a user input handler is lost. For example:

js

async function handleClick() {
  let result = await someAsyncFunction();

  // this will fail, because the handler lost its "user action handler" status
  browser.sidebarAction.open();
}

browser.browserAction.onClicked.addListener(handleClick);