Welcome What's new in Chrome extensions Get help with Chrome extensions API reference Samples
Welcome What's new in Chrome extensions Get help with Chrome extensions API reference Samples

Match patterns

Published on Updated on

Overview

Extensions use match patterns to specify a group of URLs. They are mainly used to declare host permissions along with other permissions to use certain Chrome APIs or when injecting content scripts. Extensions also use match patterns in:

What is a match pattern?

A match pattern is a URL that begins with a permitted scheme, separated by a ://, followed by a host and path. It can contain wildcard (*) characters. Most match patterns are composed of three parts:

<scheme>://<host>/<path>

Each part can use wildcards *. Below is a detailed description:

  • scheme: Must include a valid scheme: 'http', 'https', 'file', 'ftp', or 'urn'. The wildcard * only matches http or https.

  • host: A hostname (www.example.com), a * before the hostname to match subdomains (*.example.com), or just a wildcard *.

  • path: Must start with / and be present. If alone, it is treated as /*. For example: /*, /foo*, or /foo/bar. Each '*' matches 0 or more characters.

Special cases

<all_urls>
It matches any URL that starts with a permitted scheme, including any pattern listed under valid patterns. This is a broad host permission, meaning the Chrome web store review may take longer.
file:///
Allows your extension to run on local files. It has no host and requires the user to manually [grant access][permissions-allow-access].
Localhost URLs and IP addresses
To match any localhost port during development, use http://localhost:*/*. For example, it will match any paths under http://localhost:8080 or http://localhost:3000. For IP addresses, specify the address plus a wildcard in the path. For example: http://127.0.0.1/*. Another approach is to use http://*:*/* which will match localhost, IP addresses and any port.
Top Level domain match patterns
Top Level domain match patterns like http://google.*/* are not supported. They should be listed individually. For example: http://google.es/* and http://google.fr/*.

Examples

✅ Valid patterns

PatternWhat it doesExamples
https://*/*Matches any URL that uses the https schemehttps://www.google.com/
https://example.org/foo/bar.html
http://*/*Matches any URL that uses the http schemehttp://74.125.127.100/search
http://example.com/
https://*/foo*Matches any URL that uses the https scheme, on any host, and a path that starts with /foohttps://example.com/foo/bar.html https://www.google.com/foo
https://*.google.com/foo*barMatches any URL that uses the https scheme, is on a google.com host, and the path starts with /foo and ends with barhttps://www.google.com/foo/baz/bar
https://docs.google.com/foobar
file:///foo*Matches any local file whose path starts with /foofile:///foo/bar.html
file:///foo
http://127.0.0.1/*Matches any URL that uses the http scheme and is on the host 127.0.0.1http://127.0.0.1/
http://127.0.0.1/foo/bar.html
http://localhost/*Matches any localhost porthttp://localhost:3000
http://localhost:8080
*://mail.google.com/*Matches any URL that starts with http://mail.google.com or https://mail.google.com.http://mail.google.com/foo/baz/bar
https://mail.google.com/foobar
urn:*Matches any URL that starts with urn:.urn:uuid:54723bea-c94e-480e-80c8-a69846c3f582
urn:uuid:cfa40aff-07df-45b2-9f95-e023bcf4a6da

❌ Invalid patterns

Here are some examples of invalid match patterns:

Invalid patternWhy it's invalid
https://www.google.comNo path
https://*foo/bar'*' in the host can be followed only by a '.' or '/'
https://foo.*.bar/baz If '*' is in the host, it must be the first character
http:/barMissing scheme separator ("/" should be "//")
foo://*Invalid scheme
chrome://*Unsupported scheme
chrome-extension://*Unsupported scheme
about:*Unsupported scheme.
Success

Content scripts can be injected into related frames like about:, data:, etc by setting "match_origin_as_fallback" to "true" in the manifest. See Injecting in related frames for details.

Updated on Improve article

This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.