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 matcheshttporhttps.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 underhttp://localhost:8080orhttp://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 usehttp://*:*/*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/*andhttp://google.fr/*.
Examples
✅ Valid patterns
| Pattern | What it does | Examples |
|---|---|---|
https://*/* | Matches any URL that uses the https scheme | https://www.google.com/ https://example.org/foo/bar.html |
http://*/* | Matches any URL that uses the http scheme | http://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 /foo | https://example.com/foo/bar.html https://www.google.com/foo |
https://*.google.com/foo*bar | Matches any URL that uses the https scheme, is on a google.com host, and the path starts with /foo and ends with bar | https://www.google.com/foo/baz/bar https://docs.google.com/foobar |
file:///foo* | Matches any local file whose path starts with /foo | file:///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.1 | http://127.0.0.1/ http://127.0.0.1/foo/bar.html |
http://localhost/* | Matches any localhost port | http://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 pattern | Why it's invalid |
|---|---|
https://www.google.com | No 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:/bar | Missing scheme separator ("/" should be "//") |
foo://* | Invalid scheme |
chrome://* | Unsupported scheme |
chrome-extension://* | Unsupported scheme |
about:* | Unsupported scheme. |
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