Match patterns

Host permissions and content script matching are based on a set of URLs defined by match patterns. A match pattern is essentially a URL that begins with a permitted scheme (http, https, file, or ftp, and that can contain '*' characters. The special pattern <all_urls> matches any URL that starts with a permitted scheme. Each match pattern has 3 parts:

• scheme—for example, http or file or *

  Access to file URLs isn't automatic. The user must visit the extensions management page and opt in to file access for each extension that requests it.

• host—for example, www.google.com or *.google.com or *; if the scheme is file, there is no host part

• path—for example, /*, /foo*, or /foo/bar. The path must be present in a host permission, but is always treated as /*.

Here's the basic syntax:

<url-pattern> := <scheme>://<host><path>
<scheme> := '*' | 'http' | 'https' | 'file' | 'ftp' | 'urn'
<host> := '*' | '*.' <any char except '/' and '*'>+
<path> := '/' <any chars>

The meaning of '*' depends on whether it's in the scheme, host, or path part. If the scheme is *, then it matches either http or https, and not file, ftp, or urn. If the host is just *, then it matches any host. If the host is *._hostname_, then it matches the specified host or any of its subdomains. In the path section, each '*' matches 0 or more characters. The following table shows some valid patterns.

Note: urn scheme is available since Chrome 91.

Here are some examples of invalid pattern matches:

Some schemes are not supported in all contexts.

Exclude matches and globs

Specified page matching is customizable by including the following fields in a declarative registration.

The content script will be injected into a page if both of the following are true:

• Its URL matches any matches pattern and any include_globs pattern
• The URL doesn't also match an exclude_matches or exclude_globs pattern. Because the matches property is required, exclude_matches, include_globs, and exclude_globs can only be used to limit which pages will be affected.

The following extension injects the content script into https://www.nytimes.com/ health but not into https://www.nytimes.com/ business .

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

chrome.scripting.registerContentScripts([{
  id : "test",
  matches : [ "https://*.nytimes.com/*" ],
  excludeMatches : [ "*://*/*business*" ],
  js : [ "contentScript.js" ],
}]);

Glob properties follow a different, more flexible syntax than match patterns. Acceptable glob strings are URLs that may contain "wildcard" asterisks and question marks. The asterisk * matches any string of any length, including the empty string, while the question mark ? matches any single character.

For example, the glob https://???.example.com/foo/* matches any of the following:

• https://www.example.com/foo/bar
• https://the.example.com/foo/

However, it does not match the following:

• https://my.example.com/foo/bar
• https://example.com/foo/
• https://www.example.com/foo

This extension injects the content script into https://www.nytimes.com/arts/index.html and https://www.nytimes.com/jobs/index.html, but not into https://www.nytimes.com/sports/index.html:

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

This extension injects the content script into https://history.nytimes.com and https://.nytimes.com/history, but not into https://science.nytimes.com or https://www.nytimes.com/science:

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

One, all, or some of these can be included to achieve the correct scope.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}