scripting.executeScript()
Injects a script into a target context. The script is run at document_idle
by default.
Note: This method is available in Manifest V3 or higher in Chrome and Firefox 101. In Safari and Firefox 102+, this method is also available in Manifest V2.
To use this API you must have the "scripting"
permission and permission for the target's URL, either explicitly as a host permission or using the activeTab permission. Note that some special pages do not allow this permission, including reader view, view-source, and PDF viewer pages.
In Firefox and Safari, partial lack of host permissions can result in a successful execution (with the partial results in the resolved promise). In Chrome, any missing permission prevents any execution from happening (see Issue 1325114).
The scripts you inject are called content scripts.
This is an asynchronous function that returns a Promise
.
Syntax
js
let results = await browser.scripting.executeScript(
details // object
)
Parameters
details
-
An object describing the script to inject. It contains these properties:
args
Optional-
An array of arguments to carry into the function. This is only valid if the
func
parameter is specified. The arguments must be JSON-serializable. files
Optional-
array
ofstring
. An array of path of the JS files to inject, relative to the extension's root directory. Exactly one offiles
andfunc
must be specified. func
Optional-
function
. A JavaScript function to inject. This function is serialized and then deserialized for injection. This means that any bound parameters and execution context are lost. Exactly one offiles
andfunc
must be specified. injectImmediately
Optional-
boolean
. Whether the injection into the target is triggered as soon as possible, but not necessarily prior to page load. target
-
scripting.InjectionTarget
. Details specifying the target to inject the script into. world
Optional-
scripting.ExecutionWorld
. The execution environment for a script to execute in.
Return value
A Promise
that fulfills with an array of InjectionResult
objects, which represent the result of the injected script in every injected frame.
The promise is rejected if the injection fails, such as when the injection target is invalid. When script execution has started, its result is included in the result, whether successful (as result
) or unsuccessfully (as error
).
Each InjectionResult
object has these properties:
frameId
-
number
. The frame ID associated with the injection. result
Optional-
any
. The result of the script execution. error
Optional-
any
. If an error occurs, contains the value the script threw or rejected with. Typically this is an error object with a message property but it could be any value (including primitives and undefined).Chrome does not support the
error
property yet (see Issue 1271527: Propagate errors from scripting.executeScript to InjectionResult). As an alternative, runtime errors can be caught by wrapping the code to execute in a try-catch statement. Uncaught errors are also reported to the console of the target tab.
The result of the script is the last evaluated statement, which is similar to the results seen if you executed the script in the Web Console (not any console.log()
output). For example, consider a script like this:
js
let foo='my result'; foo;
Here the results array contains the string "my result
" as an element.
The script result must be a structured cloneable value in Firefox or a JSON-serializable value in Chrome. The Chrome incompatibilities article discusses this difference in more detail in the Data cloning algorithm section.
Examples
This example executes a one-line code snippet in the active tab:
js
browser.action.onClicked.addListener(async (tab) => {
try {
await browser.scripting.executeScript({
target: {
tabId: tab.id,
},
func: () => {
document.body.style.border = "5px solid green";
},
});
} catch (err) {
console.error(`failed to execute script: ${err}`);
}
});
This example executes a script from a file (packaged with the extension) called "content-script.js"
. The script is executed in the active tab. The script is executed in subframes and the main document:
js
browser.action.onClicked.addListener(async (tab) => {
try {
await browser.scripting.executeScript({
target: {
tabId: tab.id,
allFrames: true,
},
files: ["content-script.js"],
});
} catch (err) {
console.error(`failed to execute script: ${err}`);
}
});
Browser compatibility
BCD tables only load in the browser
Note: This API is based on Chromium's chrome.scripting
API.