Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Popup, Options and Content Scripts

The Options Page

Add a settings page to your Chrome extension with options_ui, save preferences to chrome.storage.sync, validate input, reset defaults and react to changes in other parts.

Most extensions need settings: a theme, a list of sites, an API key, a feature switch. Chrome gives you a dedicated place for them, the options page. Users reach it from the extension's card on chrome://extensions, from the toolbar icon's context menu (Options), and you can open it from code.

Declare it

JSON
{
  "options_ui": {
    "page": "options.html",
    "open_in_tab": true
  }
}
  • open_in_tab: true shows it in a normal browser tab, with room for a real form.
  • open_in_tab: false (the default for options_ui) embeds it in a small dialog on the extensions page, which is fine for two or three settings.
  • The older options_page key always opens a tab. Do not set both.

Open the page from your own code with:

JavaScript
chrome.runtime.openOptionsPage();

A settings form

HTML
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>Settings</title>
</head>
<body>
  <form id="form">
    <label>Theme
      <select name="theme">
        <option value="auto">Match system</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
      </select>
    </label>
    <label><input type="checkbox" name="notify"> Show notifications</label>
    <label>Blocked words (one per line)
      <textarea name="words" rows="4"></textarea>
    </label>
    <button type="submit">Save</button>
    <button type="button" id="reset">Reset to defaults</button>
    <p id="status" role="status"></p>
  </form>
  <script src="options.js" type="module"></script>
</body>
</html>

Defaults, loading and saving

Settings code follows a fixed recipe. Keep defaults in one object, merge stored values over it, and write only on Save.

JavaScript
const DEFAULTS = { theme: "auto", notify: true, words: [] };

async function loadSettings() {
  const stored = await chrome.storage.sync.get(DEFAULTS);
  return stored;
}

async function saveSettings(values) {
  await chrome.storage.sync.set(values);
}

Passing an object to get() means "return these keys, and use my value for any that are missing", which is a neat way to apply defaults.

sync or local?

Area Limit Synced across devices Best for
chrome.storage.sync about 100 KB total, 8 KB per item Yes (signed-in Chrome) Small settings
chrome.storage.local about 10 MB (more with unlimitedStorage) No Caches, larger data

Never put secrets or personal data you would not want in the user's Google account into sync. The storage API is covered fully in the storage chapter.

Try the form

The stand-in below implements load, validate, save and reset against a fake storage with the same shape as chrome.storage.sync. Change the values and press Save, then reload the "page" by pressing the button.

Options page with defaults (fake storage)

Save as you type, or on Save?

Both are valid. Auto-save on every change feels modern and avoids "did I save?" questions, but needs validation on each input and a debounce for text fields. An explicit Save button is simpler and allows cancel. Whichever you choose, tell the user what happened with a status message.

Reacting to changes elsewhere

When settings change, other parts of the extension should notice without polling. Listen for storage changes in the service worker, popup or content script:

JavaScript
chrome.storage.onChanged.addListener((changes, areaName) => {
  if (areaName !== "sync") return;
  if (changes.theme) applyTheme(changes.theme.newValue);
});

changes maps each changed key to { oldValue, newValue }. Content scripts can use this to update a page the moment the user flips a switch in the options page.

JS storage.onChanged, simulated

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does chrome.runtime.openOptionsPage() do?

    It opens whichever page you declared with options_ui or options_page.
  2. 2. Which storage area syncs data across the user's signed-in Chrome browsers?

    chrome.storage.sync is synced by Chrome, but is small (about 100 KB in total).
  3. 3. How can a content script learn immediately that a setting changed?

    onChanged fires in every extension context that registered a listener.
  4. 4. What does chrome.storage.sync.get({ theme: "auto" }) return when nothing is stored?

    An object argument supplies default values for missing keys.

Summary

  • Declare the page with options_ui; open it with chrome.runtime.openOptionsPage().
  • Keep defaults in one object and merge stored values over them.
  • Use storage.sync for small settings and storage.local for bigger data.
  • Validate input and show a status message.
  • Use storage.onChanged to apply changes everywhere instantly.

Next: Content Scripts Basics