Content Scripts
To create a content script, seeEntrypoint Types.
Context
The first argument to a content script'smain
function is its "context".
// entrypoints/example.content.tsexport default defineContentScript({ main(ctx) {},});
This object is responsible for tracking whether or not the content script's context is "invalidated". Most browsers, by default, do not stop content scripts if the extension is uninstalled, updated, or disabled. When this happens, content scripts start reporting this error:
Error: Extension context invalidated.
Thectx
object provides several helpers to stop asynchronous code from running once the context is invalidated:
ctx.addEventListener(...);ctx.setTimeout(...);ctx.setInterval(...);ctx.requestAnimationFrame(...);// and more
You can also check if the context is invalidated manually:
if (ctx.isValid) { // do something}// ORif (ctx.isInvalid) { // do something}
CSS
In regular web extensions, CSS for content scripts is usually a separate CSS file, that is added to a CSS array in the manifest:
{ "content_scripts": [ { "css": ["content/style.css"], "js": ["content/index.js"], "matches": ["*://*/*"] } ]}
In WXT, to add CSS to a content script, simply import the CSS file into your JS entrypoint, and WXT will automatically add the bundled CSS output to thecss
array.
// entrypoints/example.content/index.tsimport './style.css';export default defineContentScript({ // ...});
To create a standalone content script that only includes a CSS file:
Create the CSS file:
entrypoints/example.content.css
Use the
build:manifestGenerated
hook to add the content script to the manifest:wxt.config.tstsexport default defineConfig({ hooks: { 'build:manifestGenerated': (wxt,manifest)=> { manifest.content_scripts??= []; manifest.content_scripts.push({ // Build extension once to see where your CSS get's written to css: ['content-scripts/example.css'], matches: ['*://*/*'], }); }, },});
UI
WXT provides 3 built-in utilities for adding UIs to a page from a content script:
- Integrated -
createIntegratedUi
- Shadow Root -
createShadowRootUi
- IFrame -
createIframeUi
Each has their own set of advantages and disadvantages.
Method | Isolated Styles | Isolated Events | HMR | Use page's context |
---|---|---|---|---|
Integrated | ❌ | ❌ | ❌ | ✅ |
Shadow Root | ✅ | ✅ (off by default) | ❌ | ✅ |
IFrame | ✅ | ✅ | ✅ | ❌ |
Integrated
Integrated content script UIs are injected alongside the content of a page. This means that they are affected by CSS on that page.
// entrypoints/example-ui.content.tsexport default defineContentScript({ matches: ['<all_urls>'], main(ctx) { const ui = createIntegratedUi(ctx, { position:'inline', anchor:'body', onMount: (container)=> { // Append children to the container const app = document.createElement('p'); app.textContent= '...'; container.append(app); }, }); // Call mount to add the UI to the DOM ui.mount(); },});
// entrypoints/example-ui.content/index.tsimport { createApp }from 'vue';import Appfrom './App.vue';export default defineContentScript({ matches: ['<all_urls>'], main(ctx) { const ui = createIntegratedUi(ctx, { position:'inline', anchor:'body', onMount: (container)=> { // Create the app and mount it to the UI container const app = createApp(App); app.mount(container); return app; }, onRemove: (app)=> { // Unmount the app when the UI is removed app.unmount(); }, }); // Call mount to add the UI to the DOM ui.mount(); },});
// entrypoints/example-ui.content/index.tsximport ReactDOMfrom 'react-dom/client';import Appfrom './App.tsx';export default defineContentScript({ matches: ['<all_urls>'], main(ctx) { const ui = createIntegratedUi(ctx, { position:'inline', anchor:'body', onMount: (container)=> { // Create a root on the UI container and render a component const root = ReactDOM.createRoot(container); root.render(<App />); return root; }, onRemove: (root)=> { // Unmount the root when the UI is removed root.unmount(); }, }); // Call mount to add the UI to the DOM ui.mount(); },});
// entrypoints/example-ui.content/index.tsimport Appfrom './App.svelte';import { mount, unmount }from 'svelte';export default defineContentScript({ matches: ['<all_urls>'], main(ctx) { const ui = createIntegratedUi(ctx, { position:'inline', anchor:'body', onMount: (container)=> { // Create the Svelte app inside the UI container return mount(App, { target: container }); }, onRemove: (app)=> { // Destroy the app when the UI is removed unmount(app); }, }); // Call mount to add the UI to the DOM ui.mount(); },});
// entrypoints/example-ui.content/index.tsimport { render }from 'solid-js/web';export default defineContentScript({ matches: ['<all_urls>'], main(ctx) { const ui = createIntegratedUi(ctx, { position:'inline', anchor:'body', onMount: (container)=> { // Render your app to the UI container const unmount = render(()=> <div>...</div>, container); return unmount; }, onRemove: (unmount)=> { // Unmount the app when the UI is removed unmount(); }, }); // Call mount to add the UI to the DOM ui.mount(); },});
See theAPI Reference for the complete list of options.
Shadow Root
Often in web extensions, you don't want your content script's CSS affecting the page, or vise-versa. TheShadowRoot
API is ideal for this.
WXT'screateShadowRootUi
abstracts all theShadowRoot
setup away, making it easy to create UIs whose styles are isolated from the page. It also supports an optionalisolateEvents
parameter to further isolate user interactions.
To usecreateShadowRootUi
, follow these steps:
- Import your CSS file at the top of your content script
- Set
cssInjectionMode: "ui"
insidedefineContentScript
- Define your UI with
createShadowRootUi()
- Mount the UI so it is visible to users
// 1. Import the styleimport './style.css';export default defineContentScript({ matches: ['<all_urls>'], // 2. Set cssInjectionMode cssInjectionMode:'ui', async main(ctx) { // 3. Define your UI const ui = await createShadowRootUi(ctx, { name:'example-ui', position:'inline', anchor:'body', onMount(container) { // Define how your UI will be mounted inside the container const app = document.createElement('p'); app.textContent= 'Hello world!'; container.append(app); }, }); // 4. Mount the UI ui.mount(); },});
// 1. Import the styleimport './style.css';import { createApp }from 'vue';import Appfrom './App.vue';export default defineContentScript({ matches: ['<all_urls>'], // 2. Set cssInjectionMode cssInjectionMode:'ui', async main(ctx) { // 3. Define your UI const ui = await createShadowRootUi(ctx, { name:'example-ui', position:'inline', anchor:'body', onMount: (container)=> { // Define how your UI will be mounted inside the container const app = createApp(App); app.mount(container); return app; }, onRemove: (app)=> { // Unmount the app when the UI is removed app?.unmount(); }, }); // 4. Mount the UI ui.mount(); },});
// 1. Import the styleimport './style.css';import ReactDOMfrom 'react-dom/client';import Appfrom './App.tsx';export default defineContentScript({ matches: ['<all_urls>'], // 2. Set cssInjectionMode cssInjectionMode:'ui', async main(ctx) { // 3. Define your UI const ui = await createShadowRootUi(ctx, { name:'example-ui', position:'inline', anchor:'body', onMount: (container)=> { // Container is a body, and React warns when creating a root on the body, so create a wrapper div const app = document.createElement('div'); container.append(app); // Create a root on the UI container and render a component const root = ReactDOM.createRoot(app); root.render(<App />); return root; }, onRemove: (root)=> { // Unmount the root when the UI is removed root?.unmount(); }, }); // 4. Mount the UI ui.mount(); },});
// 1. Import the styleimport './style.css';import Appfrom './App.svelte';import { mount, unmount }from 'svelte';export default defineContentScript({ matches: ['<all_urls>'], // 2. Set cssInjectionMode cssInjectionMode:'ui', async main(ctx) { // 3. Define your UI const ui = await createShadowRootUi(ctx, { name:'example-ui', position:'inline', anchor:'body', onMount: (container)=> { // Create the Svelte app inside the UI container return mount(App, { target: container }); }, onRemove: (app)=> { // Destroy the app when the UI is removed unmount(app); }, }); // 4. Mount the UI ui.mount(); },});
// 1. Import the styleimport './style.css';import { render }from 'solid-js/web';export default defineContentScript({ matches: ['<all_urls>'], // 2. Set cssInjectionMode cssInjectionMode:'ui', async main(ctx) { // 3. Define your UI const ui = await createShadowRootUi(ctx, { name:'example-ui', position:'inline', anchor:'body', onMount: (container)=> { // Render your app to the UI container const unmount = render(()=> <div>...</div>, container); }, onRemove: (unmount)=> { // Unmount the app when the UI is removed unmount?.(); }, }); // 4. Mount the UI ui.mount(); },});
See theAPI Reference for the complete list of options.
Full examples:
IFrame
If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page,HMR is supported.
WXT provides a helper function,createIframeUi
, which simplifies setting up the IFrame.
Create an HTML page that will be loaded into your IFrame:
html<!-- entrypoints/example-iframe.html --><!doctype html><html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Your Content Script IFrame</title> </head> <body> <!-- ... --> </body></html>
Add the page to the manifest's
web_accessible_resources
:wxt.config.tstsexport default defineConfig({ manifest: { web_accessible_resources: [ { resources: ['example-iframe.html'], matches: [...], }, ], },});
Create and mount the IFrame:
tsexport default defineContentScript({ matches: ['<all_urls>'], main(ctx) { // Define the UI const ui = createIframeUi(ctx, { page:'/example-iframe.html', position:'inline', anchor:'body', onMount: (wrapper,iframe)=> { // Add styles to the iframe like width iframe.width= '123'; }, }); // Show UI to user ui.mount(); },});
See theAPI Reference for the complete list of options.
Isolated World vs Main World
By default, all content scripts run in an isolated context where only the DOM is shared with the webpage it is running on - an "isolated world". In MV3, Chromium introduced the ability to run content scripts in the "main" world - where everything, not just the DOM, is available to the content script, just like if the script were loaded by the webpage.
You can enable this for a content script by setting theworld
option:
export default defineContentScript({ world:'MAIN',});
However, this approach has several notable drawbacks:
- Doesn't support MV2
world: "MAIN"
is only supported by Chromium browsers- Main world content scripts don't have access to the extension API
Instead, WXT recommends injecting a script into the main world manually using it'sinjectScript
function. This will address the drawbacks mentioned before.
injectScript
supports both MV2 and MV3injectScript
supports all browsers- Having a "parent" content script means you can send messages back and forth, making it possible to access the extension API
To useinjectScript
, we need two entrypoints, one content script and one unlisted script:
📂 entrypoints/ 📄 example.content.ts 📄 example-main-world.ts
// entrypoints/example-main-world.tsexport default defineUnlistedScript(()=> { console.log('Hello from the main world');});
// entrypoints/example.content.tsexport default defineContentScript({ matches: ['*://*/*'], async main() { console.log('Injecting script...'); await injectScript('/example-main-world.js', { keepInDom:true, }); console.log('Done!'); },});
export default defineConfig({ manifest: { // ... web_accessible_resources: [ { resources: ["example-main-world.js"], matches: ["*://*/*"], } ] }});
injectScript
works by creating ascript
element on the page pointing to your script. This loads the script into the page's context so it runs in the main world.
injectScript
returns a promise, that when resolved, means the script has been evaluated by the browser and you can start communicating with it.
Warning:run_at
Caveat
For MV3,injectScript
is synchronous and the injected script will be evaluated at the same time as your the content script'srun_at
.
However for MV2,injectScript
has tofetch
the script's text content and create an inline<script>
block. This means for MV2, your script is injected asynchronously and it will not be evaluated at the same time as your content script'srun_at
.
Mounting UI to dynamic element
In many cases, you may need to mount a UI to a DOM element that does not exist at the time the web page is initially loaded. To handle this, use theautoMount
API to automatically mount the UI when the target element appears dynamically and unmount it when the element disappears. In WXT, theanchor
option is used to target the element, enabling automatic mounting and unmounting based on its appearance and removal.
export default defineContentScript({ matches: ['<all_urls>'], main(ctx) { const ui = createIntegratedUi(ctx, { position:'inline', // It observes the anchor anchor:'#your-target-dynamic-element', onMount: (container)=> { // Append children to the container const app = document.createElement('p'); app.textContent= '...'; container.append(app); }, }); // Call autoMount to observe anchor element for add/remove. ui.autoMount(); },});
TIP
When theui.remove
is called,autoMount
also stops.
See theAPI Reference for the complete list of options.
Dealing with SPAs
It is difficult to write content scripts for SPAs (single page applications) and websites using HTML5 history mode for navigation because content scripts are only ran on full page reloads. SPAs and websites that take advantage of HTML5 history modedo not perform a full reload when changing paths, and thus your content script isn't going to be ran when you expect it to be.
Let's look at an example. Say you want to add a UI to YouTube when watching a video:
export default defineContentScript({ matches: ['*://*.youtube.com/watch*'], main(ctx) { console.log('YouTube content script loaded'); mountUi(ctx); },});function mountUi(ctx: ContentScriptContext): void { // ...}
You're only going to see "YouTube content script loaded" when reloading the watch page or when navigating directly to it from another website.
To get around this, you'll need to manually listen for the path to change and run your content script when the URL matches what you expect it to match.
const watchPattern = new MatchPattern('*://*.youtube.com/watch*');export default defineContentScript({ matches: ['*://*.youtube.com/*'], main(ctx) { ctx.addEventListener(window,'wxt:locationchange', ({newUrl })=> { if (watchPattern.includes(newUrl))mainWatch(ctx); }); },});function mainWatch(ctx: ContentScriptContext) { mountUi(ctx);}