Skip to content

Latest commit

 

History

History
138 lines (122 loc) · 5.95 KB

index.md

File metadata and controls

138 lines (122 loc) · 5.95 KB
Raw
title slug page-type browser-compat
options_ui
Mozilla/Add-ons/WebExtensions/manifest.json/options_ui
webextension-manifest-key
webextensions.manifest.options_ui

{{AddonSidebar}}

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

Use the options_ui key to define an options page for your extension.

The options page contains settings for the extension. The user can access it from the browser's add-ons manager, and you can open it from within your extension using {{WebExtAPIRef("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 {{WebExtAPIRef("extension.getBackgroundPage()")}}, or a reference to the {{domxref("Window")}} of any of the pages running within your extension with {{WebExtAPIRef("extension.getViews()")}}. Alternately, you can communicate between the JavaScript for your options page and your background script(s) using {{WebExtAPIRef("runtime.sendMessage()")}}, {{WebExtAPIRef("runtime.onMessage")}}, or {{WebExtAPIRef("runtime.connect()")}}. The latter (or {{WebExtAPIRef("runtime.Port")}} equivalents) can also be used to share options between your background script(s) and your content script(s).

In general, you will want to store options changed on option pages using the {{WebExtAPIRef("storage", "storage API", "", "true")}} to either {{WebExtAPIRef("storage.sync()")}} (if you want the settings synchronized across all instances of that browser that the user is logged into), or {{WebExtAPIRef("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 {{WebExtAPIRef("storage.onChanged")}}.

Syntax

The options_ui key is an object with the following contents:

Name Type Description
browser_style
{{optional_inline}}
{{deprecated_inline}} 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 is deprecated in Manifest V3, and support will be removed in 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_inline}}		 Boolean

Defaults to false.

If true, the options page will open in a normal browser tab, rather than being integrated into the browser's add-ons manager.

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

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

Browser compatibility

{{Compat}}

See also