details

An object describing the script to inject. It contains these properties:

argsOptional

An array of arguments to carry into the function. This is only valid if thefunc parameter is specified. The arguments must be JSON-serializable.

filesOptional

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.

funcOptional

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.

injectImmediatelyOptional

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.

worldOptional

scripting.ExecutionWorld. The execution environment for a script to execute in.

APromise that fulfills with an array ofInjectionResult 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 (asresult) or unsuccessfully (aserror).

EachInjectionResult object has these properties:

frameId

number. The frame ID associated with the injection.

resultOptional

any. The result of the script execution.

errorOptional

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 theerror property yet (seeIssue 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 theWeb Console (not anyconsole.log() output). For example, consider a script like this:

let foo = "my result";foo;

Here the results array contains the string"my result" as an element.

The script result must be astructured cloneable value in Firefox or aJSON-serializable value in Chrome. TheChrome incompatibilities article discusses this difference in more detail in theData cloning algorithm section.

This example executes a one-line code snippet in the active tab:

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:

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}`);  }});