content\_scripts
================

|  |  |
| --- | --- |
| Type | `Array` |
| Mandatory | No |
| Manifest version | 2 or higher |
| Example | 
```json
"content\_scripts": [
  {
    "matches": ["\*://\*.mozilla.org/\*"],
    "js": ["borderify.js"]
  }
]
```
 |

Instructs the browser to load content scripts into web pages whose URL matches a given pattern.

This key is an array. Each item is an object which:

* **must** contain a key named **`matches`**, which specifies the URL patterns to be matched in order for the scripts to be loaded;
* **may** contain keys named **`js`** and **`css`**, which list scripts and/or stylesheets to be loaded into matching pages; and
* **may** contain a number of other properties that control finer aspects of how and when content scripts are loaded.

Details of all the keys you can include are given in the table below.

| Name | Type | Description |
| --- | --- | --- |
| `all_frames` | `Boolean` | 
`true`

 Inject the scripts specified in
 `js` and
 `css` into all frames matching the
 specified URL requirements, even if the frame is not the topmost
 frame in a tab. This does not inject into child frames where only
 their parent matches the URL requirements and the child frame does
 not match the URL requirements. The URL requirements are checked
 for each frame independently.


**Note:** This also applies to any tracker or ad
 that uses iframes, which means that enabling this could make
 your content script get called dozens of times on some pages.


`false`

 Inject only into frames matching the URL requirements which are the
 topmost frame in a tab.


Defaults to `false`. |
| `css` | `Array` | 
 An array of paths, relative to `manifest.json`, referencing
 CSS files that will be injected into matching pages.


 Files are injected in the order given, and at the time specified by
 `run\_at`.


**Note:** Firefox resolves URLs in injected CSS files
 relative to the CSS file itself, rather than to the page it's
 injected into.

 |
| `exclude_globs` | `Array` | 
 An array of strings containing wildcards. See
 Matching URL patterns below.
  |
| `exclude_matches` | `Array` | 
 An array of
 match patterns. See Matching URL patterns below.
  |
| `include_globs` | `Array` | 
 An array of strings containing wildcards. See
 Matching URL patterns below.
  |
| `js` | `Array` | 
 An array of paths, relative to `manifest.json`, referencing
 JavaScript files that will be injected into matching pages.


 Files are injected in the order given. This means that, for example,
 if you include jQuery here followed by another content script, like
 this:


```json
"js": ["jquery.js", "my-content-script.js"]
```

Then, `"my-content-script.js"` can use jQuery.

 The files are injected after any files in
 `css`, and at the time specified by
 `run\_at`.
  |
| `match\_about\_blank` | `Boolean` | 
 Insert the content scripts into pages whose URL is
 `"about:blank"` or `"about:srcdoc"`, if the URL
 of the page that opened or created this page
 matches the patterns specified in
 the rest of the `content_scripts` key.


 This is especially useful to run scripts in empty iframes, whose URL
 is `"about:blank"`. To do this you should also set the
 `all_frames` key.


 For example, suppose you have a `content_scripts` key like
 this:


```json
  "content\_scripts": [
    {
      "js": ["my-script.js"],
      "matches": ["https://example.org/"],
      "match\_about\_blank": true,
      "all\_frames": true
    }
  ]
```

 If the user loads `https://example.org/`, and this page
 embeds an empty iframe, then `"my-script.js"` will be
 loaded into the iframe.


**Note:** `match_about_blank` is supported
 in Firefox from version 52.


 Note that in Firefox, content scripts won't be injected into empty
 iframes at `"document_start"`, even if you specify that
 value in `run\_at` .

 |
| `matches` | `Array` | 
 An array of
 match patterns. See
 Matching URL patterns below.

This is the only mandatory key. |
| `run_at` | `String` | 
 This option determines when the files specified in
 `css` and
 `js` are injected. You can supply one of
 three strings here, each of which identifies a state in the process of
 loading a document. The states directly correspond to
 `Document.readyState`:


`"document_start"`
Corresponds to `loading`. The DOM is still loading.
`"document_end"`

 Corresponds to `interactive`. The DOM has finished
 loading, but resources such as scripts and images may still be
 loading.

`"document_idle"`

 Corresponds to `complete`. The document and all its
 resources have finished loading.


The default value is `"document_idle"`.

 In all cases, files in `js` are injected
 after files in `css`.
  |

Matching URL patterns
---------------------

The `"content_scripts"` key attaches content scripts to documents based on URL matching: if the document's URL matches the specification in the key, then the script will be attached. There are four properties inside `"content_scripts"` that you can use for this specification:

`matches`

an array of match patterns

`exclude_matches`

an array of match patterns

`include_globs`

an array of globs

`exclude_globs`

an array of globs

To match one of these properties, a URL must match at least one of the items in its array. For example, given a property like:


```json
"matches": ["\*://\*.example.org/\*", "\*://\*.example.com/\*"]
```


Both `http://example.org/` and `http://example.com/` will match.

Since `matches` is the only mandatory key, the other three keys are used to limit further the URLs that match. To match the key as a whole, a URL must:

* match the `matches` property
* AND match the `include_globs` property, if present
* AND NOT match the `exclude_matches` property, if present
* AND NOT match the `exclude_globs` property, if present
### globs

A *glob* is just a string that may contain wildcards.

There are two types of wildcard, and you can combine them in the same glob:

1. `*` matches zero or more characters
2. `?` matches exactly one character.

For example: `"*na?i"` would match `"illuminati"` and `"annunaki"`, but not `"sagnarelli"`.

Example
-------


```json
"content\_scripts": [
  {
    "matches": ["\*://\*.mozilla.org/\*"],
    "js": ["borderify.js"]
  }
]
```


This injects a single content script `borderify.js` into all pages under `mozilla.org` or any of its subdomains, whether served over HTTP or HTTPS.


```json
  "content\_scripts": [
    {
      "exclude\_matches": ["\*://developer.mozilla.org/\*"],
      "matches": ["\*://\*.mozilla.org/\*"],
      "js": ["jquery.js", "borderify.js"]
    }
  ]
```


This injects two content scripts into all pages under `mozilla.org` or any of its subdomains except `developer.mozilla.org`, whether served over HTTP or HTTPS.

The content scripts see the same view of the DOM and are injected in the order they appear in the array, so `borderify.js` can see global variables added by `jquery.js`.

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

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