The JavaScript world for a user script to execute within.

Enum

Properties

• documentId

  string

  The document associated with the injection.

• error

  string optional

  The error, if any.error andresult are mutually exclusive.

• frameId

  number

  The frame associated with the injection.

• result

  any optional

  The result of the script execution.

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

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

• frameIds

  number[] optional

  The IDs of specific frames to inject into.

• tabId

  number

  The ID of the tab into which to inject.

Properties

• allFrames

  boolean optional

  If 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.

• excludeGlobs

  string[] optional

  Specifies wildcard patterns for pages this user script will NOT be injected into.

• excludeMatches

  string[] optional

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

• id

  string

  The ID of the user script specified in the API call. This property must not start with a '_' as it's reserved as a prefix for generated script IDs.

• includeGlobs

  string[] optional

  Specifies wildcard patterns for pages this user script will be injected into.

• js

  ScriptSource[] optional

  The list of ScriptSource objects defining sources of scripts to be injected into matching pages. This property must be specified for ${ref:register}, and when specified it must be a non-empty array.

• matches

  string[] optional

  Specifies which pages this user script will be injected into. SeeMatch Patterns for more details on the syntax of these strings. This property must be specified for ${ref:register}.

• runAt

  RunAt optional

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

• world

  ExecutionWorld optional

  The JavaScript execution environment to run the script in. The default is`USER_SCRIPT`.

• worldId

  string optional

  Chrome 133+

  Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid ifworld is omitted or isUSER_SCRIPT. Values with leading underscores (_) are reserved.

Properties

• code

  string optional

  A string containing the JavaScript code to inject. Exactly one offile orcode must be specified.

• file

  string optional

  The path of the JavaScript file to inject relative to the extension's root directory. Exactly one offile orcode must be specified.

Properties

• ids

  string[] optional

  getScripts only returns scripts with the IDs specified in this list.

Properties

• injectImmediately

  boolean optional

  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.

• js

  ScriptSource[]

  The list of ScriptSource objects defining sources of scripts to be injected into the target.

• target

  InjectionTarget

  Details specifying the target into which to inject the script.

• world

  ExecutionWorld optional

  The JavaScript "world" to run the script in. The default isUSER_SCRIPT.

• worldId

  string optional

  Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid ifworld is omitted or isUSER_SCRIPT. Values with leading underscores (_) are reserved.

Properties

• csp

  string optional

  Specifies the world csp. The default is the`ISOLATED` world csp.

• messaging

  boolean optional

  Specifies whether messaging APIs are exposed. The default isfalse.

• worldId

  string optional

  Chrome 133+

  Specifies the ID of the specific user script world to update. If not provided, updates the properties of the default user script world. Values with leading underscores (_) are reserved.

chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Configures the`USER_SCRIPT` execution environment.

Parameters

• properties

  WorldProperties

  Contains the user script world configuration.

• 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.

chrome.userScripts.execute(
  injection: UserScriptInjection,
  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

• injection

  UserScriptInjection

• callback

  function optional

  Thecallback parameter looks like:

  (result: InjectionResult[]) => void

  • result

    InjectionResult[]

Returns

• Promise<InjectionResult[]>

  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.

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Returns all dynamically-registered user scripts for this extension.

Parameters

• filter

  UserScriptFilter optional

  If specified, this method returns only the user scripts that match it.

• callback

  function optional

  Thecallback parameter looks like:

  (scripts: RegisteredUserScript[]) => void

  • scripts

    RegisteredUserScript[]

Returns

• Promise<RegisteredUserScript[]>

  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.

chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Retrieves all registered world configurations.

Parameters

• callback

  function optional

  Thecallback parameter looks like:

  (worlds: WorldProperties[]) => void

  • worlds

    WorldProperties[]

Returns

• Promise<WorldProperties[]>

  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.

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Registers one or more user scripts for this extension.

Parameters

• scripts

  RegisteredUserScript[]

  Contains a list of user scripts to be 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.

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Resets the configuration for a user script world. Any scripts that inject into the world with the specified ID will use the default world configuration.

Parameters

• worldId

  string optional

  The ID of the user script world to reset. If omitted, resets the default world's configuration.

• 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.

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Unregisters all dynamically-registered user scripts for this extension.

Parameters

• filter

  UserScriptFilter optional

  If specified, this method unregisters only the user scripts that match it.

• 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.

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Updates one or more user scripts for this extension.

Parameters

• scripts

  RegisteredUserScript[]

  Contains a list of user 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.