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.

You can define a keyboard shortcut that opens the popup using the special "_execute_browser_action" and "_execute_page_action" shortcuts. See the documentation for the commands manifest.json key. However, you can't open the popup programmatically from your add-on's JavaScript: it can only be opened in response to a user action.

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.

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.

Document Tags and Contributors

 Contributors to this page: wbamberg
 Last updated by: wbamberg,