In an extension's pages (like the background page), the userScripts API provides a register() API method. This method is very similar to the contentScripts.register() API method (e.g. they both return a promise which is resolved to an API object which provides an unregister() method for unregistering the registered script from all the child processes), with some differences in the options supported.

This is an asynchronous method that returns a Promise.


const registeredUserScript = await browser.userScripts.register(
  userScriptOptions       // object
await registeredUserScript.unregister();


object. A UserScriptOptions object representing the content scripts to register. It has similar syntax to the options supported by contentScripts.register().

The UserScriptOptions object has the following properties:

scriptMetadata Optional
a JSON object which contains some metadata properties associated with the registered userScripts
allFrames Optional
Same as all_frames in the user_scripts key.
excludeGlobs Optional
Same as exclude_globs in the user_scripts key.
excludeMatches Optional
Same as exclude_matches in the user_scripts key.
includeGlobs Optional
Same as include_globs in the user_scripts key.
js Optional
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.
matchAboutBlank Optional
Same as match_about_blank in the user_scripts key.
Same as matches in the user_scripts key.
runAt Optional
Same as run_at in the user_scripts key.

Unlike content script options, the userScriptOptions object does not have a css property. Use contentScripts.register() to dynamically register/unregister stylesheets).

Return value

A Promise that will be fulfilled with a RegisteredUserScript object that you can use to unregister the this particular userScript.

Note: Currently, user scripts are unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register a user script from an extension page that persists at least as long as you want the user scripts to stay registered.

Browser compatibility

No compatibility data found. Please contribute data for "webextensions.api.userScripts.register" (depth: 10) to the MDN compatibility data repository.

See also