Match patterns
Match patterns are a way to specify groups of URLs: a match pattern matches a specific set of URLs. They are used in WebExtensions APIs in a few places, most notably to specify which documents to loadcontent scripts into, and to specify which URLs to addwebRequest listeners to.
APIs that use match patterns usually accept a list of match patterns, and will perform the appropriate action if the URL matches any of the patterns. See, for example, thecontent_scripts key in manifest.json.
Match pattern structure
Note:Some browsers don't support certain schemes.Check theBrowser compatibility table for details.
All match patterns are specified as strings. Apart from the special<all_urls> pattern, match patterns consist of three parts:scheme,host, andpath. The scheme and host are separated by://.
<scheme>://<host><path>
scheme
Thescheme component may take one of two forms:
| Form | Matches |
|---|---|
* | Only "http" and "https" and in some browsers also"ws" and "wss". |
One ofhttp,https,ws,wss,ftp,data,file, or(chrome-)extension. | Only the given scheme. |
host
Thehost component may take one of three forms:
| Form | Matches |
|---|---|
* | Any host. |
*. followed by part of the hostname. | The given host and any of its subdomains. |
| A complete hostname, without wildcards. | Only the given host. |
host must not include a port number.
host is optional only if thescheme is "file".
Note that the wildcard may only appear at the start.
path
Thepath component must begin with a/.
After that, it may subsequently contain any combination of the* wildcard and any of the characters that are allowed in URL paths or query strings. Unlikehost, thepath component may contain the* wildcard in the middle or at the end, and the* wildcard may appear more than once.
The value for thepath matches against the string which is the URL path plus theURL query string. This includes the? between the two, if the query string is present in the URL. For example, if you want to match URLs on any domain where the URL path ends withfoo.bar, then you need to use an array of Match Patterns like["*://*/*foo.bar", "*://*/*foo.bar?*"]. The?* is needed, rather than justbar*, in order to anchor the ending* as applying to the URL query string and not some portion of the URL path.
Neither theURL fragment identifier, nor the# which precedes it, are considered as part of thepath.
Note:The path pattern string should not include a port number. Adding a port, as in:http://localhost:1234/* causes the match pattern to be ignored. However,http://localhost:1234 will match withhttp://localhost/*.
<all_urls>
The special value<all_urls> matches all URLs under any of the supported schemes: that is "http", "https", "ws", "wss", "ftp", "data", and "file".
Examples
| Pattern | Example matches | Example non-matches |
|---|---|---|
Match all URLs. |
|
|
Match all HTTP, HTTPS and WebSocket URLs. |
|
|
Match all HTTP, HTTPS and WebSocket URLs that are hosted at "mozilla.org" or one of its subdomains. |
|
|
Match all HTTP, HTTPS and WebSocket URLs that are hosted at exactly "mozilla.org/". |
|
|
Match only "ftp://mozilla.org/". | ftp://mozilla.org |
|
Match HTTPS URLs on any host, whose path is "path". |
|
|
Match HTTPS URLs on any host, whose path is "path/" and which has no URL query string. |
|
|
Match HTTPS URLs only at "mozilla.org", with any URL path and URL query string. |
|
|
Match only this URL, or this URL with any URL fragment. |
| Anything else. |
Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle. Will match URLs with query strings, if the string ends in a |
|
|
Match any FILE URL whose path begins with "blah". |
| file:///bleh/(unmatched path) |
Invalid match patterns
| Invalid pattern | Reason |
|---|---|
resource://path/ | Unsupported scheme. |
https://mozilla.org | No path. |
https://mozilla.*.org/ | "*" in host must be at the start. |
https://*zilla.org/ | "*" in host must be the only character or be followed by ".". |
http*://mozilla.org/ | "*" in scheme must be the only character. |
https://mozilla.org:80/ | Host must not include a port number. |
*://* | Empty path: this should be*://*/*. |
file://* | Empty path: this should befile:///*. |