options_ui

Type Object
Mandatory No
Manifest version 2 or higher
Example
json
"options_ui": {
  "page": "options/options.html"
}

Use the options_ui key to define an options page for your extension. You use this page to enable users to modify your extension's settings.

The way the user opens the page is browser-dependent and also depends on the open_in_tab setting. Your extension can also open the page using runtime.openOptionsPage().

You specify options_ui as a path to an HTML file packaged with your extension. The HTML file 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. However, it runs in a different scope than your background scripts.

If you want to share data or functions between the JavaScript on your options page and your background script(s), you can do so directly by obtaining a reference to the Window of your background scripts by using extension.getBackgroundPage(), or a reference to the Window of any of the pages running within your extension with extension.getViews(). Alternately, you can communicate between the JavaScript for your options page and your background script(s) using runtime.sendMessage(), runtime.onMessage, or runtime.connect(). The latter (or runtime.Port equivalents) can also be used to share options between your background script(s) and your content script(s).

In general, you want to store options changed on option pages using the storage API to either storage.sync (if you want the settings synchronized across all instances of that browser that the user is logged into), or storage.local (if the settings are local to the current machine/profile). If you do so and your background script(s) (or content script(s)) need to know about the change, your script(s) might choose to add a listener to storage.onChanged.

Syntax

The options_ui key is an object with the following contents:

Name Type Description
browser_style
Optional
in Manifest V3.
Boolean

Optional, defaulting to:

  • true in Manifest V2 and prior to Firefox 115 in Manifest V3.
  • false in Manifest V3 from Firefox 115.

Do not set browser_style to true: it's not supported in Manifest V3, 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. When setting dimensions, be aware that this stylesheet sets box-sizing: border-box (see box-sizing).

open_in_tab
Optional
Boolean
  • If false, the options page opens in the browser's add-on manager.
  • If true, the options page opens in a normal browser tab.

Defaults to false.

page String

Mandatory.

The path to an HTML file containing the specification of your options page.

The path is relative to the location of manifest.json itself.

Example

json
"options_ui": {
  "page": "options/options.html"
}

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
options_ui
Chrome – Full support
Chrome 40 (Release date: 2015-01-21)
footnote Full support
Edge – Full support
Edge 79 (Release date: 2020-01-15)
footnote Full support
Firefox – Full support
Firefox 48 (Release date: 2016-08-02)
footnote Full support
Opera – Full support
Opera 27 (Release date: 2015-01-27)
footnote Full support
Safari – Full support
Safari 14 (Release date: 2020-09-16)
footnote Full support
Firefox for Android – Full support
Firefox for Android 57 (Release date: 2017-11-28)
footnote Full support
Safari on iOS – Full support
Safari on iOS 15 (Release date: 2021-09-20)
footnote Full support
browser_style
Chrome – No support
Chrome
footnote No support
Edge – No support
Edge
footnote No support
Firefox – Full support
Firefox 55 (Release date: 2017-08-08)
footnote
footnote Removed from Manifest V3 in Firefox 118. See Browser styles for more details.
Opera – No support
Opera
footnote No support
Safari – No support
Safari
footnote No support
Firefox for Android – No support
Firefox for Android
footnote No support
Safari on iOS – No support
Safari on iOS
footnote No support
open_in_tab
Chrome – Full support
Chrome 40 (Release date: 2015-01-21)
footnote Full support
Edge – Full support
Edge 79 (Release date: 2020-01-15)
footnote Full support
Firefox – Full support
Firefox 48 (Release date: 2016-08-02)
footnote Full support
Opera – Partial support
Opera 27 (Release date: 2015-01-27)
footnote Partial support
footnote Options pages are always opened in a separate browser tab.
Safari – Partial support
Safari 14 (Release date: 2020-09-16)
footnote Partial support
footnote Options pages are always opened in a separate browser tab.
Firefox for Android – Full support
Firefox for Android 57 (Release date: 2017-11-28)
footnote Full support
Safari on iOS – Partial support
Safari on iOS 15 (Release date: 2021-09-20)
footnote Partial support
footnote Options pages are always opened in a separate browser tab.
page
Chrome – Full support
Chrome 40 (Release date: 2015-01-21)
footnote Full support
Edge – Full support
Edge 79 (Release date: 2020-01-15)
footnote Full support
Firefox – Full support
Firefox 48 (Release date: 2016-08-02)
footnote Full support
Opera – Full support
Opera 27 (Release date: 2015-01-27)
footnote Full support
Safari – Full support
Safari 14 (Release date: 2020-09-16)
footnote Full support
Firefox for Android – Full support
Firefox for Android 57 (Release date: 2017-11-28)
footnote Full support
Safari on iOS – Full support
Safari on iOS 15 (Release date: 2021-09-20)
footnote Full support

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
See implementation notes.

See also