Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 Β· Popup, Options and Content Scripts

Building a Popup

Build a toolbar popup for your Chrome extension. Configure action.default_popup, size the window, load scripts correctly, query the active tab and handle the popup lifetime.

The popup is the small window that opens when a user clicks your toolbar icon. It is the most common user interface in extensions: a quick view, a few buttons, maybe a form. Technically it is an ordinary HTML page served from your extension, with access to chrome.* APIs.

Declare it

JSON
{
  "manifest_version": 3,
  "name": "Tab Counter",
  "version": "1.0.0",
  "permissions": ["tabs"],
  "action": {
    "default_title": "Count my tabs",
    "default_popup": "popup.html",
    "default_icon": { "16": "icons/icon-16.png", "32": "icons/icon-32.png" }
  }
}

You can also set the popup at runtime with chrome.action.setPopup({ popup: "other.html" }), useful for showing a "sign in" popup first and a main popup later.

The HTML page

HTML
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="popup.css" />
  </head>
  <body>
    <h1>Tab Counter</h1>
    <p id="count">Counting…</p>
    <button id="close-dupes">Close duplicate tabs</button>
    <script src="popup.js" type="module"></script>
  </body>
</html>

Remember the two rules for all extension pages: no inline scripts and no remote scripts. type="module" is allowed and lets you import your own files.

Size and layout

A popup sizes itself to its content, within limits: minimum 25 Γ— 25 px, maximum 800 Γ— 600 px. Set a width on body so the popup does not jump around as content loads:

CSS
body {
  width: 320px;
  min-height: 120px;
  margin: 0;
  padding: 16px;
  font: 14px/1.4 system-ui, sans-serif;
}

Beyond the maximum, content scrolls. Avoid designing a popup that needs a lot of scrolling; open a tab or side panel instead.

Talking to the browser

The popup can call most APIs directly. This popup.js counts tabs in the current window:

JavaScript
const tabs = await chrome.tabs.query({ currentWindow: true });
document.getElementById("count").textContent =
  `${tabs.length} tab${tabs.length === 1 ? "" : "s"} in this window`;

To act on the current tab (the one the user is looking at), query for it:

JavaScript
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
console.log(tab.url, tab.title);

Reading tab.url and tab.title needs either the tabs permission or the activeTab permission (granted when the user clicks the icon).

The popup is short-lived

This is the most important thing to know. The popup is created fresh each time it opens and destroyed as soon as it loses focus. Clicking elsewhere closes it, destroying every variable. So:

  • Load what you need at the top of popup.js each time.
  • Save anything the user entered (a draft, a toggle) to chrome.storage as they type.
  • Do not run long jobs in the popup: start them in the service worker.
  • Opening DevTools on the popup keeps it open (right-click the popup β†’ Inspect), which is the easy way to debug it.
sequenceDiagram
    participant U as User
    participant P as Popup page
    participant S as chrome.storage
    U->>P: Click toolbar icon
    P->>S: get({ theme })
    S-->>P: { theme: "dark" }
    P->>U: Render popup
    U->>P: Toggle option
    P->>S: set({ theme: "light" })
    U->>P: Click outside
    Note over P: Popup closed and destroyed

State must live in storage, not in the popup.

Stand-in: a popup you can try

Below is a working popup UI with a fake chrome.tabs. The logic that counts and finds duplicate tabs is exactly what the real extension would use. The only thing replaced is the data source.

Tab counter popup (fake tabs)

Persisting a draft

Here is the draft-saving pattern with a fake storage object. Type something, then press the "Close popup" button to destroy the popup's UI, then "Open popup" to rebuild it: the draft comes back from storage.

Surviving the popup lifetime

Check your understanding

Quick check Β· 3 questions

of 3 answered You scored / 3 Β· perfect!

  1. 1. What are the maximum dimensions of a popup?

    Chrome caps popups at 800 by 600 pixels. Larger content scrolls.
  2. 2. What happens to a popup's JavaScript variables when the user clicks outside it?

    The popup page is torn down when it loses focus, so persistent data must go into chrome.storage.
  3. 3. Which is the right way to include popup logic?

    MV3 extension pages only run scripts that ship in the package and are loaded with src.

Summary

  • Set action.default_popup to an HTML page in your package.
  • Size it with CSS; it is limited to 800 Γ— 600 px.
  • Query the active tab with chrome.tabs.query({ active: true, currentWindow: true }).
  • The popup is destroyed when it closes: store state in chrome.storage.
  • Right-click β†’ Inspect to debug it.

Next: Popup UI Patterns and Communication