Implement a settings page

Note: The following example may not work, since the storage API doesn't work with a temporary Addon ID, see also https://bugzil.la/1323228.

A settings page gives users a way to see and change settings (sometimes also called "preferences" or "options") for the extension.

With WebExtension APIs, settings are generally stored using the storage API. Implementing a settings page is a three-step process:

  • Write an HTML file that displays settings and lets the user change them.
  • Write a script, included from the HTML file, that populates the settings page from storage and updates stored settings when the user changes them.
  • Set the path to the HTML file as the options_ui key in manifest.json. By doing this, the HTML document will be shown in the browser's add-on manager, alongside the extension's name and description.

Note: You can also open this page programmatically using the runtime.openOptionsPage() function.

A simple extension

First, we'll write an extension that adds a blue border to every page the user visits.

Create a new directory called settings, then create a file called manifest.json inside it with the following contents:

{

  "manifest_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["borderify.js"]
    }
  ]

}

This extension instructs the browser to load a content script called "borderify.js" into all web pages the user visits.

Next, create a file called borderify.js inside the settings directory, and give it these contents:

document.body.style.border = "10px solid blue";

This just adds a blue border to the page.

Now install the extension and test it — open up any web page you like:

Adding settings

Now let's create a settings page to allow the user to set the color of the border.

First, update manifest.json so it has these contents:

{

  "manifest_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["borderify.js"]
    }
  ],

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

  "permissions": ["storage"],

  "browser_specific_settings": {
    "gecko": {
      "id": "[email protected]"
    }
  }

}

We've added three new manifest keys:

options_ui
This sets an HTML document to be the settings page (also called options page) for this extension.
permissions
We'll use the storage API to store the settings, and we need to ask permission to use this API.
browser_specific_settings
You have to include an extension id in order to save and retrieve settings from synchronized storage.

Next, because we've promised to provide options.html, let's create it. Create a file with that name inside the settings directory, and give it the following contents:

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
  </head>

  <body>

    <form>
        <label>Border color<input type="text" id="color" ></label>
        <button type="submit">Save</button>
    </form>

    <script src="options.js"></script>

  </body>

</html>

This defines a <form> with a labeled text <input> and a submit <button>. It also includes a script called options.js.

Create options.js, again in the settings directory, and give it the following contents:

function saveOptions(e) {
  e.preventDefault();
  browser.storage.sync.set({
    color: document.querySelector("#color").value
  });
}

function restoreOptions() {

  function setCurrentChoice(result) {
    document.querySelector("#color").value = result.color || "blue";
  }

  function onError(error) {
    console.log(`Error: ${error}`);
  }

  let getting = browser.storage.sync.get("color");
  getting.then(setCurrentChoice, onError);
}

document.addEventListener("DOMContentLoaded", restoreOptions);
document.querySelector("form").addEventListener("submit", saveOptions);

This does two things:

  • When the document has loaded, it fetches the value of "color" from storage using storage.sync.get(). If the value isn't set, it uses the default "blue". This retrieves the values from the sync storage area.
  • When the user submits the form by clicking Save, it stores the value of the textbox using storage.sync.set(). This saves the value to the sync storage area.

Note: Specifying a separate .js file is required. You cannot use inline JavaScript.

You could store the settings values in local storage instead if you feel that local storage is preferable for your extension.

Note: The implementation of storage.sync in Firefox relies on the Add-on ID. If you use storage.sync, you must set an ID for your extension using the browser_specific_settings key in manifest.json, as shown in the sample manifest above.

Finally, update borderify.js to read the border color from storage:

Warning: Due to a bug in browser.storage.local.get() in Firefox versions prior to 52, the following code will not function.

To make it function in Firefox versions below 52, the two occurrences of item.color in onGot() must be changed to item[0].color.

 function onError(error) {
  console.log(`Error: ${error}`);
}

function onGot(item) {
  let color = "blue";
  if (item.color) {
    color = item.color;
  }
  document.body.style.border = "10px solid " + color;
}

let getting = browser.storage.sync.get("color");
getting.then(onGot, onError);

At this point, the complete extension should look like this:

settings/
    borderify.js
    manifest.json
    options.html
    options.js

Now:

  • reload the extension
  • load a web page
  • open the settings page and change the border color
  • reload the web page to see the difference.

In Firefox you can access the settings page by visiting about:addons and clicking the Preferences button next to the extension's entry.

Learn more

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page