Skip to content
Tutorials Center
My learning

Topics

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

Popup UI Patterns and State

Design better popups: small state machines, toggles and lists, loading and error states, keyboard access, dark mode with prefers-color-scheme, and clean separation of logic.

A popup is small, but users judge your whole extension by it. This lesson covers practical patterns for building popup interfaces that feel quick and dependable: a state object that drives the view, loading and error states, accessible controls, dark mode and a code layout that is easy to test.

Keep one state object

Instead of changing the DOM everywhere, keep a single object that describes the popup and write one render() function that turns it into HTML.

JavaScript
const state = {
  status: "loading",   // "loading" | "ready" | "error"
  enabled: false,
  items: [],
  error: null,
};

function setState(patch) {
  Object.assign(state, patch);
  render();
}

This "state in, view out" idea is how every UI framework works, and in a popup you can do it in thirty lines of plain JavaScript. Each event handler calls setState, and render redraws. Only save to chrome.storage what must survive; derived values (like a count) can be recomputed.

Show all three states

A popup that starts empty and fills in a moment later looks broken. Always render:

  1. Loading: a short message or skeleton. Storage and tab queries are fast, but a network call may not be.
  2. Ready: the real interface.
  3. Error: a plain explanation plus a Try again button. Never leave the user with a blank popup.
stateDiagram-v2
    [*] --> loading
    loading --> ready: data loaded
    loading --> error: request failed
    error --> loading: Try again
    ready --> loading: Refresh

Three states cover almost every popup.

A complete example

This stand-in uses a fake chrome.storage that sometimes fails, so you can see all three states. Press Reload a few times; every third load fails on purpose.

Loading, ready and error states

Accessibility and polish

Popups are used by keyboard and screen reader users too, and it costs little to help them:

  • Use real <button>, <input> and <label> elements, not styled <div>s.
  • Put keyboard focus somewhere sensible when the popup opens. The first interactive control is focused by default.
  • Give icon-only buttons an aria-label.
  • Announce changes with role="status" or role="alert".
  • Keep contrast high and tap targets at least 32 px.

Dark mode

The popup does not inherit Chrome's theme automatically, but prefers-color-scheme works:

CSS
:root { color-scheme: light dark; }
body { background: Canvas; color: CanvasText; }
@media (prefers-color-scheme: dark) {
  .card { background: #1f2937; border-color: #374151; }
}

color-scheme: light dark is the shortcut: form controls and default colors adapt for free.

Separate logic from the DOM

A popup that mixes everything in one 400-line script is hard to fix. Split by role:

TEXT
popup/
  popup.html
  popup.js      ← wiring: events, render()
  logic.js      ← pure functions: count, sort, filter
  api.js        ← thin wrappers around chrome.* (easy to fake in tests)

Pure functions in logic.js take plain values and return plain values, so you can test them in Node without Chrome. The wrapper layer in api.js is the only file that mentions chrome. You will use this structure in the testing chapter as well.

JS A pure function you can test anywhere

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

No output.

Passing data to a new window

When a popup is too small, open a bigger page in a tab or window:

JavaScript
await chrome.tabs.create({ url: chrome.runtime.getURL("dashboard.html") });

chrome.runtime.getURL("path") turns a package path into a full chrome-extension://… URL. The popup then closes itself with window.close() if you want.

Check your understanding

Quick check Β· 3 questions

of 3 answered You scored / 3 Β· perfect!

  1. 1. Why use a single state object and a render() function?

    One source of truth and one renderer avoids the UI getting out of sync with the data.
  2. 2. Which three states should most popups handle?

    A popup that never shows loading or error states looks broken when data is slow or fails.
  3. 3. What does chrome.runtime.getURL("dashboard.html") return?

    It builds the full extension URL for a packaged file, so you can open it in a tab.

Summary

  • Drive the popup from one state object and a render() function.
  • Show loading, ready and error states.
  • Use native controls, labels and role="alert" for accessibility.
  • Support dark mode with color-scheme and prefers-color-scheme.
  • Keep pure logic apart from chrome.* wrappers so it is testable.

Next: The Options Page