Popup vs Options

Chrome extensions support two distinct UI surfaces: a popup that appears when the user clicks your toolbar icon, and an options page that opens as a full browser tab. Choosing the right one depends on what the user needs to accomplish.

Quick comparison

	Popup	Options page
How it opens	Click the toolbar icon	Right-click icon → Options, or `chrome.runtime.openOptionsPage()`
Persistence	Closes when the user clicks away	Stays open until the user navigates away
Best for	Quick actions, current-tab info, status	Configuration, account settings, bulk setup
Size	Small (typically 300–400px wide)	Full browser tab
Declared in manifest	`"action": { "default_popup": "popup.html" }`	`"options_page": "options.html"`

Use the popup for interactions that take a few seconds: toggling a setting, showing a count, triggering a one-time action, or displaying status information about the current page. Manifest declaration:

{
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icons/icon32.png",
    "default_title": "Open My Extension"
  }
}

Minimal popup.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <link rel="stylesheet" href="popup.css" />
  </head>
  <body>
    <h1>Word Counter</h1>
    <p id="count">Loading...</p>
    <button id="count-btn">Count words on page</button>
    <script src="popup.js"></script>
  </body>
</html>

popup.js — trigger an action and display the result:

document.getElementById("count-btn").addEventListener("click", () => {
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
    chrome.tabs.sendMessage(tabs[0].id, { type: "COUNT_WORDS" }, (response) => {
      document.getElementById("count").textContent = `${response.count} words on this page`;
    });
  });
});

The popup’s JavaScript execution context is destroyed when the popup closes. Do not use the popup to manage long-running state — use chrome.storage or the background service worker for that.

The options page

Use the options page for settings the user configures once and rarely changes: API keys, default behaviors, account information, or bulk data management. Manifest declaration:

{
  "options_page": "options.html"
}

For options pages that open in a smaller panel instead of a full tab, use options_ui:

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

options.js — save and load settings:

const form = document.getElementById("settings-form");

// Load saved settings when the page opens
chrome.storage.sync.get(["apiKey", "autoRun"], ({ apiKey, autoRun }) => {
  if (apiKey) document.getElementById("api-key").value = apiKey;
  if (autoRun !== undefined) document.getElementById("auto-run").checked = autoRun;
});

// Save settings on submit
form.addEventListener("submit", (e) => {
  e.preventDefault();
  const settings = {
    apiKey: document.getElementById("api-key").value.trim(),
    autoRun: document.getElementById("auto-run").checked,
  };
  chrome.storage.sync.set(settings, () => {
    document.getElementById("status").textContent = "Settings saved.";
    setTimeout(() => { document.getElementById("status").textContent = ""; }, 2000);
  });
});

Open the options page programmatically (from the popup or background worker):

chrome.runtime.openOptionsPage();

When to use each

Use the popup when...

The user needs to see current status (e.g., “3 trackers blocked on this page”)
A single click or toggle is the entire interaction
The UI relates to what the user is currently doing on the page
Speed matters — the user expects an instant response

Use the options page when...

The user needs to enter credentials or API keys
There are multiple settings grouped into sections
The user needs to read and manage saved data
The interaction requires more screen space or multi-step input

You can include both. A common pattern is a popup that shows a summary and a link to the options page: “Manage settings →“

Prompt Extensy to include each

Popup only:

“Add a toolbar popup that shows the word count of the current page and lets the user copy it to the clipboard.”

Options page only:

“Create an options page where users can enter their OpenAI API key and choose the default summarization length.”

Both:

“Build an extension with a popup for quick one-click summarization and an options page for setting the API key, summary length, and preferred language.”

Extensy will generate the HTML, CSS, and JavaScript for each surface and wire them together with chrome.storage for shared state.

Fundamentals

Advanced Topics

Popup vs Options

Quick comparison

The options page

When to use each

Use the popup when...

Use the options page when...

Prompt Extensy to include each

​Quick comparison

​The popup

​The options page

​When to use each

Use the popup when...

Use the options page when...

​Prompt Extensy to include each

Quick comparison

The popup

The options page

When to use each

Prompt Extensy to include each