Building a Chrome Extension with React

React can be a great choice for building a Chrome extension when the extension needs an interactive interface. It provides reusable components and a familiar way to manage UI state, making it useful for browser tools such as task managers, note-taking apps, productivity helpers, and custom dashboards.

A Chrome extension is not a single web page. It can include a popup, an options page, content scripts that interact with websites, and a background service worker. React is typically used to build the popup or options page, while Chrome’s extension APIs connect those pages to browser features.

How a Chrome Extension Is Structured

• Popup: The small interface that opens when a user clicks the extension icon.
• Options page: A page for settings and preferences.
• Content script: JavaScript that runs on web pages the extension is permitted to access.
• Service worker: A background script that handles events and browser API tasks. In Manifest V3, it runs as an event-driven service worker rather than a continuously running page.
• Manifest: A required JSON file that describes the extension, its permissions, and its entry points.

React generally belongs in the popup or options page. Content scripts and service workers have different roles and do not need to be written in React.

Getting Started

A common approach is to use a React project setup tool such as Vite, then configure the build to produce the files Chrome expects. The finished extension must include a manifest.json file and the compiled JavaScript, CSS, and HTML assets.

A simple Manifest V3 configuration might look like this:

{


  "manifest_version": 3,


  "name": "React Example Extension",


  "version": "1.0.0",


  "description": "A simple extension with a React popup.",


  "action": {


    "default_popup": "index.html"


  }


}

Here, Chrome opens index.html when the user clicks the extension icon. That page can load the React application created by the build process. The exact file paths depend on the project’s bundler configuration.

Connecting React to Chrome APIs

React components can use Chrome extension APIs to read or store settings, send messages, or interact with tabs. For example, an extension can save a user preference with the storage API. The storage permission must be included in the manifest:

{


  "manifest_version": 3,


  "name": "React Example Extension",


  "version": "1.0.0",


  "permissions": ["storage"],


  "action": {


    "default_popup": "index.html"


  }


}

A React component can then read and update a preference:

import { useEffect, useState } from "react";





function App() {


  const [enabled, setEnabled] = useState(false);





  useEffect(() => {


    chrome.storage.local.get("enabled", (result) => {


      setEnabled(Boolean(result.enabled));


    });


  }, []);





  function handleChange(event) {


    const value = event.target.checked;


    setEnabled(value);


    chrome.storage.local.set({ enabled: value });


  }





  return (


    <label>


      <input


        type="checkbox"


        checked={enabled}


        onChange={handleChange}


      />


      Enable feature


    </label>


  );


}





export default App;

Chrome APIs are available in extension pages, but they are not automatically available in a regular website. During development, check that code using the chrome namespace runs only in the extension environment.

Using Content Scripts

If an extension needs to read or modify a web page, it may use a content script. Content scripts are separate from the React popup and should be registered in the manifest with appropriate site access. The popup and content script can communicate using Chrome’s messaging APIs.

Keep permissions limited to what the extension actually needs. For example, broad access to all websites may require additional user trust and can make the extension harder to review. Request only the permissions and site access necessary for its features.

Testing the Extension

1. Build the project so the output directory contains the manifest and compiled assets.
2. Open chrome://extensions in Chrome.
3. Turn on Developer mode.
4. Select Load unpacked and choose the build output directory.
5. Test the popup, permissions, and any page interactions. Check the extension’s inspection tools and Chrome DevTools for errors.

After making changes, rebuild the project and reload the extension from the extensions page. Development tools that support automatic rebuilds can make this process faster, but the extension should still be tested in Chrome itself.

Common Development Tips

• Keep the interface focused: Popup windows are small, so prioritize the extension’s most important actions.
• Separate responsibilities: Use React for UI, content scripts for page interaction, and the service worker for background events.
• Handle asynchronous work: Chrome API calls and messaging may complete later, so account for loading and error states in the interface.
• Use minimal permissions: Request only what the extension needs, and explain sensitive features clearly to users.
• Check production builds: Bundler settings, asset paths, and code splitting can affect whether the extension loads correctly.

Conclusion

Building a Chrome extension with React combines a component-based UI with Chrome’s extension platform. React works especially well for popups and settings pages, while the manifest, content scripts, service worker, and Chrome APIs provide the browser-specific functionality. With a clear project structure, careful permission choices, and thorough testing, React can help create an extension that is both maintainable and easy to use.