> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extensy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Popup vs Options

> Decide when to use a popup for quick interactions and an options page for persistent configuration in your extension.

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"` |

## The popup

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:**

```json theme={null}
{
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icons/icon32.png",
    "default_title": "Open My Extension"
  }
}
```

**Minimal popup.html:**

```html theme={null}
<!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:**

```javascript theme={null}
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`;
    });
  });
});
```

> [!NOTE]
>
> 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:**

```json theme={null}
{
  "options_page": "options.html"
}
```

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

```json theme={null}
{
  "options_ui": {
    "page": "options.html",
    "open_in_tab": false
  }
}
```

**options.js — save and load settings:**

```javascript theme={null}
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):

```javascript theme={null}
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

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.