Implementation of Popup Interface for Browser Extension
Popup is an HTML page that opens when clicking the extension icon in the toolbar. It lives from click to close (loss of focus or explicit close) and doesn't persist state between openings — this should be considered in design.
Popup Limitations
- Maximum size: ~800×600 px, Chrome limits viewport height
- Lifetime: created on opening, destroyed on closing
- No
alert(),confirm()— blocked by browser - CSP forbids
inline scriptsandeval— all JS must be in.jsfiles - Cannot be opened programmatically from content script without user gesture (in MV3)
File structure
popup/
├── popup.html
├── popup.js (or popup.tsx + build)
└── popup.css
<!-- popup.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=350">
<link rel="stylesheet" href="popup.css">
<!-- NO inline scripts — CSP violation -->
</head>
<body>
<div id="app"></div>
<script src="popup.js"></script>
</body>
</html>
React in Popup
Popup with React is standard practice for complex interfaces:
// popup/App.tsx
import { useEffect, useState } from 'react';
import browser from 'webextension-polyfill';
interface TabInfo {
url: string;
title: string;
}
export function App() {
const [tab, setTab] = useState<TabInfo | null>(null);
const [enabled, setEnabled] = useState(false);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function init() {
// Get active tab data
const [activeTab] = await browser.tabs.query({ active: true, currentWindow: true });
setTab({ url: activeTab.url ?? '', title: activeTab.title ?? '' });
// Load saved settings
const { extensionEnabled } = await browser.storage.local.get('extensionEnabled');
setEnabled(extensionEnabled ?? false);
setLoading(false);
}
init();
}, []);
async function toggleEnabled() {
const next = !enabled;
setEnabled(next);
await browser.storage.local.set({ extensionEnabled: next });
// Notify content script on active tab
if (tab) {
const [activeTab] = await browser.tabs.query({ active: true, currentWindow: true });
if (activeTab.id) {
browser.tabs.sendMessage(activeTab.id, { type: 'TOGGLE', enabled: next });
}
}
}
if (loading) return <div className="popup-loading">Loading...</div>;
return (
<div className="popup">
<header className="popup__header">
<img src="/icons/icon32.png" alt="" />
<h1>My Extension</h1>
</header>
<section className="popup__body">
<div className="popup__url" title={tab?.url}>{tab?.title}</div>
<label className="toggle">
<input
type="checkbox"
checked={enabled}
onChange={toggleEnabled}
/>
<span className="toggle__label">
{enabled ? 'Enabled' : 'Disabled'}
</span>
</label>
</section>
<footer className="popup__footer">
<button onClick={() => browser.runtime.openOptionsPage()}>
Settings
</button>
<button onClick={() => browser.tabs.create({ url: 'https://example.com/help' })}>
Help
</button>
</footer>
</div>
);
}
Size and styling
Popup should be convenient in 320–400 px width range. Typical markup:
/* popup.css */
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
width: 360px;
min-height: 200px;
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
font-size: 14px;
color: #1a1a1a;
background: #fff;
}
.popup {
display: flex;
flex-direction: column;
min-height: 100vh;
}
.popup__header {
display: flex;
align-items: center;
gap: 8px;
padding: 12px 16px;
border-bottom: 1px solid #e5e7eb;
}
.popup__body {
flex: 1;
padding: 16px;
}
.popup__footer {
display: flex;
gap: 8px;
padding: 12px 16px;
border-top: 1px solid #e5e7eb;
}
Timeline
Simple popup with toggle and storage: 1–2 days. Complex popup with React, background sync, and multiple tabs: 3–5 days.