chrome-ext-ui-react

React UI in Chrome Extensions

React works in extension popups, side panels, options pages, and content script injected UIs. Each context has unique constraints. The core challenges are: state dies with popup close, Shadow DOM is required for content script UI, and portaled components break in Shadow DOM.

State Management Rule

Extension popups render from scratch on every toolbar click and die when they lose focus. Side panels persist longer but still need storage-backed state.

Never rely on React useState alone for persistent data. Always back state with chrome.storage:

function useChromeState<T>(key: string, defaultValue: T) {
  const [value, setValue] = useState<T>(defaultValue);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    chrome.storage.local.get({ [key]: defaultValue }).then((result) => {
      setValue(result[key]);
      setLoading(false);
    });
    const listener = (changes: Record<string, chrome.storage.StorageChange>, area: string) => {
      if (area === 'local' && key in changes) setValue(changes[key].newValue);
    };
    chrome.storage.onChanged.addListener(listener);
    return () => chrome.storage.onChanged.removeListener(listener);
  }, [key]);

  const set = async (newValue: T) => {
    setValue(newValue);
    await chrome.storage.local.set({ [key]: newValue });
  };
  return [value, set, loading] as const;
}

Shadow DOM for Content Script UI

Inject extension UI into web pages using Shadow DOM to prevent CSS pollution:

export default defineContentScript({
  matches: ['<all_urls>'],
  cssInjectionMode: 'ui',
  main(ctx) {
    const ui = createShadowRootUi(ctx, {
      name: 'my-extension',
      position: 'inline',
      onMount(container) {
        const root = createRoot(container);
        root.render(<App />);
        return root;
      },
      onRemove(root) { root.unmount(); },
    });
    ui.mount();
  },
});

Fix Portaled Components

React UI libraries (Radix UI, Headless UI, Shadcn) portal modals, dialogs, and tooltips to document.body. In content scripts, this forces them outside the Shadow DOM, stripping all styles. Configure the portal container: