userScripts

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

To use the API, call register() passing in an object defining the script to register. The method returns a Promise that is resolved with a 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 userScript must be declared in the extension's manifest file using the "user_scripts" manifest 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 userScript is executed.

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

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

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

Types

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

Methods

register()
Registers the given user scripts.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
RegisteredUserScriptChrome No support NoEdge No support NoFirefox Full support 68
Full support 68
Full support 66
Disabled
Disabled From version 66: this feature is behind the extensions.webextensions.userScripts.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera No support NoFirefox Android Full support 68
unregisterChrome No support NoEdge No support NoFirefox Full support 68
Full support 68
Full support 66
Disabled
Disabled From version 66: this feature is behind the extensions.webextensions.userScripts.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera No support NoFirefox Android Full support 68

Legend

Full support  
Full support
No support  
No support
User must explicitly enable this feature.
User must explicitly enable this feature.

See also