Use this API to register user scripts, a special kind of extension content script. Registering a user script instructs the browser to insert the given content scripts into pages that match the given URL patterns.

To use the API, call userScripts.register() passing in an object defining the scripts to register. The method returns a Promise that is resolved with a userScripts.RegisteredUserScript object.

User scripts:

  • run in the extension's content processes
  • have access to the window and document global values related to the webpage it is attached to
  • have access to the same subset of WebExtension APIs available to a content script.

A user script must be declared in the extension's manifest file using the "user_scripts" key.

Once loaded and registered, the user script is executed automatically on any webpage matched by userScript registered by the same extension, before any matched contentScript is executed

Once registered, a user script has access to the API Event onBeforeScript which the APIScript can use to add an event listener which will be called right before a matched contentScript executes. This allows the user script to export a set of custom API methods to make available to the contentScript.

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.

Event Handlers

Represents the event handler code that will be executed before the associated userScript executes.


An object of this type is returned by the userScripts.register() method. It represents the user scripts that were registered by that call, and can be used to unregister the content script.


Registers the given content scripts.

Browser compatibility

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

Document Tags and Contributors

Contributors to this page: irenesmith
Last updated by: irenesmith,