userScripts (Legacy)

Warning: This is documentation for the legacy userScripts API. It's available in Firefox for Manifest V2. For functionality to work with user scripts in Manifest V3 see the new userScripts API.

Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration.

This API offers similar capabilities to contentScripts but with features suited to handling third-party scripts:

execution is in an isolated sandbox: each user script is run in an isolated sandbox within the web content processes, preventing accidental or deliberate interference among scripts.
access to the window and document global values related to the webpage the user script is attached to.
no access to WebExtension APIs or associated permissions granted to the extension: the API script, which inherits the extension's permissions, can provide packaged WebExtension APIs to registered user scripts. An API script is declared in the extension's manifest file using the "user_scripts" manifest key.

Warning: This API requires the presence of the user_scripts key in the manifest.json, even if no API script is specified. For example. user_scripts: {}.

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

Note: 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.

Types

userScripts.RegisteredUserScript: The object returned by the register() method. It represents the registered user scripts and is used to deregister the user scripts.
userScripts.UserScriptOptions: The object passed to the register() method. It represents the content scripts to register.

Methods

userScripts.register(): Registers user scripts.

Events

userScripts.onBeforeScript: An event available to the API script, registered in "user_scripts", that execute before a user script executes. Use it to trigger the export of the additional APIs provided by the API script, so they are available to the user script.

Browser compatibility

	desktop					mobile
	Chrome	Edge	Firefox	Opera	Safari	Firefox for Android	Safari on iOS
userScripts (Legacy)	Chrome – No support Chrome footnote No support	Edge – No support Edge footnote No support	Firefox – Full support Firefox 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. footnote An alternative version of this API is available for use with Manifest V3. See `userScripts`.	Opera – No support Opera footnote No support	Safari – No support Safari footnote No support	Firefox for Android – Full support Firefox for Android 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. footnote An alternative version of this API is available for use with Manifest V3. See `userScripts`.	Safari on iOS – No support Safari on iOS footnote No support
RegisteredUserScript (Legacy)	Chrome – No support Chrome footnote No support	Edge – No support Edge footnote No support	Firefox – Full support Firefox 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. For extension using Manifest V3, see `userScripts.RegisteredUserScript`.	Opera – No support Opera footnote No support	Safari – No support Safari footnote No support	Firefox for Android – Full support Firefox for Android 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. For extension using Manifest V3, see `userScripts.RegisteredUserScript`.	Safari on iOS – No support Safari on iOS footnote No support
unregister (Legacy)	Chrome – No support Chrome footnote No support	Edge – No support Edge footnote No support	Firefox – Full support Firefox 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. For extension using Manifest V3, see `userScripts.unregister`.	Opera – No support Opera footnote No support	Safari – No support Safari footnote No support	Firefox for Android – Full support Firefox for Android 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. For extension using Manifest V3, see `userScripts.unregister`.	Safari on iOS – No support Safari on iOS footnote No support
onBeforeScript (Legacy)	Chrome – No support Chrome footnote No support	Edge – No support Edge footnote No support	Firefox – Full support Firefox 68 (Release date: 2019-07-09) footnote Full support	Opera – No support Opera footnote No support	Safari – No support Safari footnote No support	Firefox for Android – Full support Firefox for Android 68 (Release date: 2019-07-09) footnote Full support	Safari on iOS – No support Safari on iOS footnote No support
register (Legacy)	Chrome – No support Chrome footnote No support	Edge – No support Edge footnote No support	Firefox – Full support Firefox 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. For extension using Manifest V3, see `userScripts.register`.	Opera – No support Opera footnote No support	Safari – No support Safari footnote No support	Firefox for Android – Full support Firefox for Android 68 (Release date: 2019-07-09) footnote footnote Only available for use in extensions using Manifest V2. For extension using Manifest V3, see `userScripts.register`.	Safari on iOS – No support Safari on iOS footnote No support
`register.cookieStoreId`	Chrome – No support Chrome footnote No support	Edge – No support Edge footnote No support	Firefox – Full support Firefox 98 (Release date: 2022-03-08) footnote Full support	Opera – No support Opera footnote No support	Safari – No support Safari footnote No support	Firefox for Android – Full support Firefox for Android 98 (Release date: 2022-03-08) footnote Full support	Safari on iOS – No support Safari on iOS footnote No support

Tip: you can click/tap on a cell for more information.

Full support: Full support
No support: No support
: See implementation notes.

userScripts (Legacy)

Types

Methods

Events

Browser compatibility

Legend

See also