tabs.executeScript()

Syntax

let executing = browser.tabs.executeScript(
  tabId,                 // optional integer
  details                // object
)

Parameters

tabId Optional

integer. The ID of the tab in which to run the script.

Defaults to the active tab of the current window.

details

An object describing the script to run.

It contains the following properties:

allFrames Optional

boolean. If true, the code is injected into all frames of the current page.

If set to true and frameId is set, it raises an error. (frameId and allFrames are mutually exclusive.)

If it is false, the code is injected only into the top frame.

Defaults to false.

code Optional

string. Code to inject, as a text string.

Warning: Don't use this property to interpolate untrusted data into JavaScript, as this could lead to a security issue.

file Optional

string. Path to a file containing the code to inject.

• In Firefox, relative URLs not starting at the extension root are resolved relative to the current page URL.
• In Chrome, these URLs are resolved relative to the extension's base URL.

To work cross-browser, you can specify the path as a relative URL, starting at the extension's root, like this: "/path/to/script.js".

frameId Optional

integer. The frame where the code should be injected.

Defaults to 0 (the top-level frame).

matchAboutBlank Optional

boolean. If true, the code is injected into embedded about:blank and about:srcdoc frames if your extension has access to their parent document. The code cannot be inserted in top-level about: frames.

Defaults to false.

runAt Optional

extensionTypes.RunAt. The earliest that the code is injected into the tab.

Defaults to "document_idle".

Return value

A Promise that resolves to an array of objects. The array's values represent the script's result in each injected frame.

The result of the script is the last evaluated statement, which is similar to the output (the results, not any console.log() output) if you executed the script in the Web Console. 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 result values must be structured cloneable (see Data cloning algorithm).

If any error occurs, the promise is rejected with an error message.

Examples

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

function onExecuted(result) {
  console.log(`We made it green`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const makeItGreen = 'document.body.style.border = "5px solid green"';

const executing = browser.tabs.executeScript({
  code: makeItGreen,
});
executing.then(onExecuted, onError);

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 as well as the main document:

function onExecuted(result) {
  console.log(`We executed in all subframes`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const executing = browser.tabs.executeScript({
  file: "/content-script.js",
  allFrames: true,
});
executing.then(onExecuted, onError);

This example executes a script from a file (packaged with the extension) called "content-script.js". The script is executed in the tab with an ID of 2:

function onExecuted(result) {
  console.log(`We executed in tab 2`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const executing = browser.tabs.executeScript(2, {
  file: "/content-script.js",
});
executing.then(onExecuted, onError);

Example extensions

• beastify
• context-menu-copy-link-with-types
• devtools-panels
• imagify
• menu-demo
• menu-remove-element

Browser compatibility