contentScripts.register()
=========================

Use this function to register one or more content scripts.

It accepts one parameter, which is an object with similar properties to the objects given in the `content_scripts` manifest key (but note that `content_scripts` is an array of objects, while the argument to `register()` is a single object).

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let registering = browser.contentScripts.register(
  contentScriptOptions       // object
)
```

### Parameters

`contentScriptOptions`

`object`. A `RegisteredContentScriptOptions` object representing the content scripts to register. It has similar syntax to the objects in the `content_scripts` manifest key array. The differences are:

* property names use camel case, rather than underscores (snake case) — for example, `excludeMatches`, not `exclude_matches`.
* the `js` and `css` properties allow you to register strings as well as URLs, so their syntax has to distinguish these types.

The `RegisteredContentScriptOptions` object has the following properties:

`allFrames` Optional

Same as `all_frames` in the `content_scripts` key.

`cookieStoreId` Optional

A string or array of strings. Registers the content script in the tabs that belong to one or more cookie store IDs. This enables scripts to be registered for all default or non-contextual identity tabs, private browsing tabs (if the extension is enabled in private browsing), the tabs of a contextual identity, or a combination of these. See Work with contextual identities for more information.

`css` Optional

An array of objects. Each object has either a property named `file`, which is a URL starting at the extension's manifest.json and pointing to a CSS file to register, or a property named `code`, which is some CSS code to register.

`excludeGlobs` Optional

Same as `exclude_globs` in the `content_scripts` key.

`excludeMatches` Optional

Same as `exclude_matches` in the `content_scripts` key.

`includeGlobs` Optional

Same as `include_globs` in the `content_scripts` key.

`js` Optional

An array of objects. Each object has either a property named `file`, which is a URL starting at the extension's manifest.json and pointing to a JavaScript file to register, or a property named `code`, which is some JavaScript code to register.

`matchAboutBlank` Optional

Same as `match_about_blank` in the `content_scripts` key.

`matches`

Same as `matches` in the `content_scripts` key.

`runAt` Optional

Same as `run_at` in the `content_scripts` key.


### Return value

A `Promise` that will be fulfilled with a `contentScripts.RegisteredContentScript` object that you can use to unregister the content scripts.

Currently, content scripts are unregistered when the related extension page (from which the content scripts were registered) is unloaded, so you should register a content script from an extension page that persists at least as long as you want the content scripts to stay registered.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example registers the `defaultCode` content script for all `.org` URLs:


```js
const defaultHosts = "\*://\*.org/\*";
const defaultCode =
  "document.body.innerHTML = '<h1>This page has been eaten<h1>'";

async function register(hosts, code) {
  return await browser.contentScripts.register({
    matches: [hosts],
    js: [{ code }],
    runAt: "document\_idle",
  });
}

let registered = register(defaultHosts, defaultCode);
```


This code registers the JS file at content\_scripts/example.js:


```js
const scriptObj = await browser.contentScripts.register({
  js: [{ file: "/content\_scripts/example.js" }],
  matches: ["<all\_urls>"],
  allFrames: true,
  runAt: "document\_start",
});
```

### Example extensions

* content-script-register