We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

Add-ons

contentScripts.register()

Use this function to register one or more content scripts.

It accepts one parameter, which is an object with similar properties to the objects given in the content_scripts manifest key (but note that content_scripts is an array of objects, while the argument to register() is a single object).

This is an asynchronous function that returns a Promise.

Syntax

var registering = browser.contentScripts.register(
  contentScriptOptions       // object
)

Parameters

contentScriptOptions

object. A RegisteredContentScriptOptions object representing the content scripts to register. It has similar syntax to the objects in the content_scripts manifest key array. The differences are:

  • property names use camelCase, rather than underscores (for example, excludeMatches, not exclude_matches
  • the js and css properties allow you to register strings as well as URLs, so their syntax has to distinguish these types.

The RegisteredContentScriptOptions object has the following properties:

allFramesOptional
Same as all_frames in the content_scripts key.
cssOptional
An array of objects. Each object has either a property named file, which is a URL starting at the extension's manifest.json and pointing to a CSS file to register, or a property named code, which is some CSS code to register.
excludeGlobsOptional
Same as exclude_globs in the content_scripts key.
excludeMatchesOptional
Same as exclude_matches in the content_scripts key.
includeGlobsOptional
Same as include_globs in the content_scripts key.
jsOptional
An array of objects. Each object has either a property named file, which is a URL starting at the extension's manifest.json and pointing to a JavaScript file to register, or a property named code, which is some JavaScript code to register.
matchAboutBlankOptional
Same as match_about_blank in the content_scripts key.
matches
Same as matches in the content_scripts key.
runAtOptional
Same as run_at in the content_scripts key.

Return value

A Promise that will be fulfilled with a contentScripts.RegisteredContentScript object that you can use to unregister the content scripts.

Note that if this object is destroyed (for example because it goes out of scope) then the content scripts will be unregistered automatically, so you should keep a reference to this object for as long as you want the content scripts to stay registered.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support No No5959 No

Examples

This example registers the defaultCode content script for all .org URLs:

const defaultHosts = "*://*.org/*";
const defaultCode = "document.body.innerHTML = '<h1>This page has been eaten<h1>'";

async function register(hosts, code) {

  return await browser.contentScripts.register({
    matches: [hosts],
    js: [{code}],
    runAt: "document_idle"
  });

}

var registered = register(defaultHosts, defaultCode);

This code registers the JS file at content_scripts/example.js:

const scriptObj = await browser.contentScripts.register({
  "js": [{file: "/content_scripts/example.js"}],
  "matches": ["<all_urls>"],
  "allFrames": true,
  "runAt": "document_start"
});

Example extensions

Document Tags and Contributors

Contributors to this page: kernp, wbamberg
Last updated by: kernp,