chrome.scripting

Description

Use thechrome.scripting API to execute script in different contexts.

Permissions

scripting

Availability

Chrome 88+MV3+

Manifest

To use thechrome.scripting API, declare the"scripting" permission in themanifest plus the host permissions for the pages to inject scripts into. Use the"host_permissions" key or the"activeTab" permission, which grants temporary host permissions. The following example uses the activeTab permission.

{ "name":"Scripting Extension", "manifest_version":3, "permissions":["scripting","activeTab"], ...}

Concepts and usage

You can use thechrome.scripting API to inject JavaScript and CSS intowebsites. This is similar to what you can do withcontentscripts. But by using thechrome.scripting namespace, extensionscan make decisions at runtime.

Injection targets

You can use thetarget parameter to specify a target to inject JavaScript orCSS into.

The only required field istabId. By default, an injection will run in themain frame of the specified tab.

functiongetTabId(){...}chrome.scripting.executeScript({target:{tabId:getTabId()},files:["script.js"],}).then(()=>console.log("script injected"));

To run in all frames of the specified tab, you can set theallFrames booleantotrue.

functiongetTabId(){...}chrome.scripting.executeScript({target:{tabId:getTabId(),allFrames:true},files:["script.js"],}).then(()=>console.log("script injected in all frames"));

You can also inject into specific frames of a tab by specifying individual frameIDs. For more information on frame IDs, see thechrome.webNavigationAPI.

functiongetTabId(){...}chrome.scripting.executeScript({target:{tabId:getTabId(),frameIds:[frameId1,frameId2]},files:["script.js"],}).then(()=>console.log("script injected on target frames"));
Note: You cannot specify both the"frameIds" and"allFrames" properties.

Injected code

Extensions can specify the code to be injected either via an external file or aruntime variable.

Files

Files are specified as strings that are paths relative to the extension's rootdirectory. The following code will inject the filescript.js into the mainframe of the tab.

functiongetTabId(){...}chrome.scripting.executeScript({target:{tabId:getTabId()},files:["script.js"],}).then(()=>console.log("injected script file"));

Runtime functions

When injecting JavaScript withscripting.executeScript(), you can specify afunction to be executed instead of a file. This function should be a functionvariable available to the current extension context.

functiongetTabId(){...}functiongetTitle(){returndocument.title;}chrome.scripting.executeScript({target:{tabId:getTabId()},func:getTitle,}).then(()=>console.log("injected a function"));
functiongetTabId(){...}functiongetUserColor(){...}functionchangeBackgroundColor(){document.body.style.backgroundColor=getUserColor();}chrome.scripting.executeScript({target:{tabId:getTabId()},func:changeBackgroundColor,}).then(()=>console.log("injected a function"));

You can work around this by using theargs property:

functiongetTabId(){...}functiongetUserColor(){...}functionchangeBackgroundColor(backgroundColor){document.body.style.backgroundColor=backgroundColor;}chrome.scripting.executeScript({target:{tabId:getTabId()},func:changeBackgroundColor,args:[getUserColor()],}).then(()=>console.log("injected a function"));

Runtime strings

If injecting CSS within a page, you can also specify a string to be used in thecss property. This option is only available forscripting.insertCSS(); youcan't execute a string usingscripting.executeScript().

functiongetTabId(){...}constcss="body { background-color: red; }";chrome.scripting.insertCSS({target:{tabId:getTabId()},css:css,}).then(()=>console.log("CSS injected"));

Handle the results

The results of executing JavaScript are passed to the extension. A single resultis included per-frame. The main frame is guaranteed to be the first index in theresulting array; all other frames are in a non-deterministic order.

functiongetTabId(){...}functiongetTitle(){returndocument.title;}chrome.scripting.executeScript({target:{tabId:getTabId(),allFrames:true},func:getTitle,}).then(injectionResults=>{for(const{frameId,result}ofinjectionResults){console.log(`Frame${frameId} result:`,result);}});

scripting.insertCSS() does not return any results.

Promises

If the resulting value of the script execution is a promise, Chrome will waitfor the promise to settle and return the resulting value.

functiongetTabId(){...}asyncfunctionaddIframe(){constiframe=document.createElement("iframe");constloadComplete=newPromise(resolve=>iframe.addEventListener("load",resolve));iframe.src="https://example.com";document.body.appendChild(iframe);awaitloadComplete;returniframe.contentWindow.document.title;}chrome.scripting.executeScript({target:{tabId:getTabId(),allFrames:true},func:addIframe,}).then(injectionResults=>{for(constframeResultofinjectionResults){const{frameId,result}=frameResult;console.log(`Frame${frameId} result:`,result);}});

Examples

Unregister all dynamic content scripts

The following snippet contains a function that unregisters all dynamic contentscripts the extension has previously registered.

asyncfunctionunregisterAllDynamicContentScripts(){try{constscripts=awaitchrome.scripting.getRegisteredContentScripts();constscriptIds=scripts.map(script=>script.id);returnchrome.scripting.unregisterContentScripts({ids:scriptIds});}catch(error){constmessage=["An unexpected error occurred while","unregistering dynamic content scripts.",].join(" ");thrownewError(message,{cause:error});}}
Key point: Unregistering content scripts will not remove scripts or styles that havealready been injected.

To try thechrome.scripting API,install thescripting sample from theChrome extension samplesrepository.

Types

ContentScriptFilter

Chrome 96+

Properties

CSSInjection

Properties

  • css

    string optional

    A string containing the CSS to inject. Exactly one offiles andcss must be specified.

  • files

    string[] optional

    The path of the CSS files to inject, relative to the extension's root directory. Exactly one offiles andcss must be specified.

  • origin

    StyleOrigin optional

    The style origin for the injection. Defaults to'AUTHOR'.

  • Details specifying the target into which to insert the CSS.

ExecutionWorld

Chrome 95+

The JavaScript world for a script to execute within.

Enum

"ISOLATED"
Specifies the isolated world, which is the execution environment unique to this extension.

"MAIN"
Specifies the main world of the DOM, which is the execution environment shared with the host page's JavaScript.

InjectionResult

Properties

  • documentId

    string

    Chrome 106+

    The document associated with the injection.

  • frameId

    number

    Chrome 90+

    The frame associated with the injection.

  • result

    any optional

    The result of the script execution.

InjectionTarget

Properties

  • allFrames

    boolean optional

    Whether the script should inject into all frames within the tab. Defaults to false. This must not be true ifframeIds is specified.

  • documentIds

    string[] optional

    Chrome 106+

    TheIDs of specific documentIds to inject into. This must not be set ifframeIds is set.

  • frameIds

    number[] optional

    TheIDs of specific frames to inject into.

  • tabId

    number

    The ID of the tab into which to inject.

RegisteredContentScript

Chrome 96+

Properties

  • allFrames

    boolean optional

    If specified true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched.

  • css

    string[] optional

    The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page.

  • excludeMatches

    string[] optional

    Excludes pages that this content script would otherwise be injected into. SeeMatch Patterns for more details on the syntax of these strings.

  • id

    string

    The id of the content script, specified in the API call. Must not start with a '_' as it's reserved as a prefix for generated script IDs.

  • js

    string[] optional

    The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.

  • matchOriginAsFallback

    boolean optional

    Chrome 119+

    Indicates whether the script can be injected into frames where the URL contains an unsupported scheme; specifically: about:, data:, blob:, or filesystem:. In these cases, the URL's origin is checked to determine if the script should be injected. If the origin isnull (as is the case for data: URLs) then the used origin is either the frame that created the current frame or the frame that initiated the navigation to this frame. Note that this may not be the parent frame.

  • matches

    string[] optional

    Specifies which pages this content script will be injected into. SeeMatch Patterns for more details on the syntax of these strings. Must be specified forregisterContentScripts.

  • persistAcrossSessions

    boolean optional

    Specifies if this content script will persist into future sessions. The default is true.

  • runAt

    RunAt optional

    Specifies when JavaScript files are injected into the web page. The preferred and default value isdocument_idle.

  • world

    ExecutionWorld optional

    Chrome 102+

    The JavaScript "world" to run the script in. Defaults toISOLATED.

ScriptInjection

Properties

  • args

    any[] optional

    Chrome 92+

    The arguments to pass to the provided function. This is only valid if thefunc parameter is specified. These arguments must be JSON-serializable.

  • files

    string[] optional

    The path of the JS or CSS files to inject, relative to the extension's root directory. Exactly one offiles orfunc must be specified.

  • injectImmediately

    boolean optional

    Chrome 102+

    Whether the injection should be triggered in the target as soon as possible. Note that this is not a guarantee that injection will occur prior to page load, as the page may have already loaded by the time the script reaches the target.

  • Details specifying the target into which to inject the script.

  • world

    ExecutionWorld optional

    Chrome 95+

    The JavaScript "world" to run the script in. Defaults toISOLATED.

  • func

    void optional

    Chrome 92+

    A JavaScript function to inject. This function will be serialized, and then deserialized for injection. This means that any bound parameters and execution context will be lost. Exactly one offiles orfunc must be specified.

    Thefunc function looks like:

    () => {...}

StyleOrigin

The origin for a style change. Seestyle origins for more info.

Enum

"AUTHOR"

"USER"

Methods

executeScript()

Promise
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Injects a script into a target context. By default, the script will be run atdocument_idle, or immediately if the page has already loaded. If theinjectImmediately property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value.

Parameters

Returns

  • Promise<InjectionResult[]>

    Chrome 90+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

getRegisteredContentScripts()

PromiseChrome 96+
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Returns all dynamically registered content scripts for this extension that match the given filter.

Parameters

Returns

  • Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

insertCSS()

Promise
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored.

Parameters

  • injection

    The details of the styles to insert.

  • callback

    function optional

    Thecallback parameter looks like:

    () => void

Returns

  • Promise<void>

    Chrome 90+

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

registerContentScripts()

PromiseChrome 96+
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Registers one or more content scripts for this extension.

Parameters

  • Contains a list of scripts to be registered. If there are errors during script parsing/file validation, or if the IDs specified already exist, then no scripts are registered.

  • callback

    function optional

    Thecallback parameter looks like:

    () => void

Returns

  • Promise<void>

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

removeCSS()

PromiseChrome 90+
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

Removes a CSS stylesheet that was previously inserted by this extension from a target context.

Parameters

  • injection

    The details of the styles to remove. Note that thecss,files, andorigin properties must exactly match the stylesheet inserted throughinsertCSS. Attempting to remove a non-existent stylesheet is a no-op.

  • callback

    function optional

    Thecallback parameter looks like:

    () => void

Returns

  • Promise<void>

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

unregisterContentScripts()

PromiseChrome 96+
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Unregisters content scripts for this extension.

Parameters

  • filter

    If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension's dynamic content scripts are unregistered.

  • callback

    function optional

    Thecallback parameter looks like:

    () => void

Returns

  • Promise<void>

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

updateContentScripts()

PromiseChrome 96+
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Updates one or more content scripts for this extension.

Parameters

  • Contains a list of scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated.

  • callback

    function optional

    Thecallback parameter looks like:

    () => void

Returns

  • Promise<void>

    Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-03-17 UTC.