URL Pattern Standard URL Pattern Living Standard — Last Updated 15 June 2026 Participate: GitHub whatwg/urlpattern (new issue, open issues) Chat on Matrix Commits: GitHub whatwg/urlpattern/commits Snapshot as of this commit @urlpatterns Tests: web-platform-tests urlpattern/ (ongoing work) Translations (non-normative): 简体中文 日本語 한국어 Abstract The URL Pattern Standard provides a web platform primitive for matching URLs based on a convenient pattern syntax. 1. URL patterns 1.1. Introduction A URL pattern consists of several components, each of which represents a pattern which could be matched against the corresponding component of a URL. It can be constructed using a string for each component, or from a shorthand string. It can optionally be resolved relative to a base URL. The shorthand "https://example.com/:category/*" corresponds to the following components: protocol "https" username "*" password "*" hostname "example.com" port "" pathname "/:category/*" search "*" hash "*" It matches the following URLs: https://example.com/products/ https://example.com/blog/our-greatest-product-ever It does not match the following URLs: https://example.com/ http://example.com/products/ https://example.com:8443/blog/our-greatest-product-ever This is a fairly simple pattern which requires most components to either match an exact string, or allows any string ("*"). The pathname component matches any path with at least two /-separated path components, the first of which is captured as "category". The shorthand "http{s}?://{:subdomain.}?shop.example/products/:id([0-9]+)#reviews" corresponds to the following components: protocol "http{s}?" username "*" password "*" hostname "{:subdomain.}?shop.example" port "" pathname "/products/:id([0-9]+)" search "" hash "reviews" It matches the following URLs: https://shop.example/products/74205#reviews https://[email protected]/products/74656#reviews http://insecure.shop.example/products/1701#reviews It does not match the following URLs: https://shop.example/products/2000 http://shop.example:8080/products/0#reviews https://nx.shop.example/products/01?speed=5#reviews https://shop.example/products/chair#reviews This is a more complicated pattern which includes: optional parts marked with ? (braces are needed to make it unambiguous exactly what is optional), and a regexp part named "id" which uses a regular expression to define what sorts of substrings match (the parentheses are necessary to mark it as a regular expression, and are not part of the regexp itself). The shorthand "../admin/*" with the base URL "https://discussion.example/forum/?page=2" corresponds to the following components: protocol "https" username "*" password "*" hostname "discussion.example" port "" pathname "/admin/*" search "*" hash "*" It matches the following URLs: https://discussion.example/admin/ https://edd:[email protected]/admin/update?id=1 It does not match the following URLs: https://discussion.example/forum/admin/ http://discussion.example:8080/admin/update?id=1 This pattern demonstrates how pathnames are resolved relative to a base URL, in a similar way to relative URLs. 1.2. The URLPattern class typedef (USVString or URLPatternInit) URLPatternInput; [Exposed=(Window,Worker)] interface URLPattern { constructor(URLPatternInput input, USVString baseURL, optional URLPatternOptions options = {}); constructor(optional URLPatternInput input = {}, optional URLPatternOptions options = {}); boolean test(optional URLPatternInput input = {}, optional USVString baseURL); URLPatternResult? exec(optional URLPatternInput input = {}, optional USVString baseURL); readonly attribute USVString protocol; readonly attribute USVString username; readonly attribute USVString password; readonly attribute USVString hostname; readonly attribute USVString port; readonly attribute USVString pathname; readonly attribute USVString search; readonly attribute USVString hash; readonly attribute boolean hasRegExpGroups; }; dictionary URLPatternInit { USVString protocol; USVString username; USVString password; USVString hostname; USVString port; USVString pathname; USVString search; USVString hash; USVString baseURL; }; dictionary URLPatternOptions { boolean ignoreCase = false; }; dictionary URLPatternResult { sequence<URLPatternInput> " id="dom-urlpatternresult-inputs">inputs; URLPatternComponentResult protocol; URLPatternComponentResult username; URLPatternComponentResult password; URLPatternComponentResult hostname; URLPatternComponentResult port; URLPatternComponentResult pathname; URLPatternComponentResult search; URLPatternComponentResult hash; }; dictionary URLPatternComponentResult { USVString input; record<USVString, (USVString or undefined)> " id="dom-urlpatterncomponentresult-groups">groups; }; Each URLPattern has an associated URL pattern, a URL pattern. urlPattern = new URLPattern(input) Constructs a new URLPattern object. The input is an object containing separate patterns for each URL component; e.g. hostname, pathname, etc. Missing components will default to a wildcard pattern. In addition, input can contain a baseURL property that provides static text patterns for any missing components. urlPattern = new URLPattern(patternString, baseURL) Constructs a new URLPattern object. patternString is a URL string containing pattern syntax for one or more components. If baseURL is provided, then patternString can be relative. This constructor will always set at least an empty string value and does not default any components to wildcard patterns. urlPattern = new URLPattern(input, options) Constructs a new URLPattern object. The options is an object containing the additional configuration options that can affect how the components are matched. Currently it has only one property ignoreCase which can be set to true to enable case-insensitive matching. Note that by default, that is in the absence of the options argument, matching is always case-sensitive. urlPattern = new URLPattern(patternString, baseURL, options) Constructs a new URLPattern object. This overrides supports a URLPatternOptions object when constructing a pattern from a patternString object, describing the patterns for individual components, and base URL. matches = urlPattern.test(input) Tests if urlPattern matches the given arguments. The input is an object containing strings representing each URL component; e.g. hostname, pathname, etc. Missing components are treated as empty strings. In addition, input can contain a baseURL property that provides values for any missing components. If urlPattern matches the input on a component-by-component basis then true is returned. Otherwise, false is returned. matches = urlPattern.test(url, baseURL) Tests if urlPattern matches the given arguments. url is a URL string. If baseURL is provided, then url can be relative. If urlPattern matches the input on a component-by-component basis then true is returned. Otherwise, false is returned. result = urlPattern.exec(input) Executes the urlPattern against the given arguments. The input is an object containing strings representing each URL component; e.g. hostname, pathname, etc. Missing components are treated as empty strings. In addition, input can contain a baseURL property that provides values for any missing components. If urlPattern matches the input on a component-by-component basis then an object is returned containing the results. Matched group values are contained in per-component group objects within the result object; e.g. matches.pathname.groups.id. If urlPattern does not match the input, then result is null. result = urlPattern.exec(url, baseURL) Executes the urlPattern against the given arguments. url is a URL string. If baseURL is provided, then input can be relative. If urlPattern matches the input on a component-by-component basis then an object is returned containing the results. Matched group values are contained in per-component group objects within the result object; e.g. matches.pathname.groups.id. If urlPattern does not match the input, then result is null. urlPattern.protocol Returns urlPattern’s normalized protocol pattern string. urlPattern.username Returns urlPattern’s normalized username pattern string. urlPattern.password Returns urlPattern’s normalized password pattern string. urlPattern.hostname Returns urlPattern’s normalized hostname pattern string. urlPattern.port Returns urlPattern’s normalized port pattern string. urlPattern.pathname Returns urlPattern’s normalized pathname pattern string. urlPattern.search Returns urlPattern’s normalized search pattern string. urlPattern.hash Returns urlPattern’s normalized hash pattern string. urlPattern.hasRegExpGroups Returns whether urlPattern contains one or more groups which uses regular expression matching. The new URLPattern(input, baseURL, options) constructor steps are: Run initialize given this, input, baseURL, and options. The new URLPattern(input, options) constructor steps are: Run initialize given this, input, null, and options. To initialize a URLPattern given a URLPattern this, URLPatternInput input, string or null baseURL, and URLPatternOptions options: Set this’s associated URL pattern to the result of create given input, baseURL, and options. The protocol getter steps are: Return this’s associated URL pattern’s protocol component’s pattern string. The username getter steps are: Return this’s associated URL pattern’s username component’s pattern string. The password getter steps are: Return this’s associated URL pattern’s password component’s pattern string. The hostname getter steps are: Return this’s associated URL pattern’s hostname component’s pattern string. The port getter steps are: Return this’s associated URL pattern’s port component’s pattern string. The pathname getter steps are: Return this’s associated URL pattern’s pathname component’s pattern string. The search getter steps are: Return this’s associated URL pattern’s search component’s pattern string. The hash getter steps are: Return this’s associated URL pattern’s hash component’s pattern string. The hasRegExpGroups getter steps are: If this’s associated URL pattern’s has regexp groups, then return true. Return false. The test(input, baseURL) method steps are: Let result be the result of match given this’s associated URL pattern, input, and baseURL if given. If result is null, return false. Return true. The exec(input, baseURL) method steps are: Return the result of match given this’s associated URL pattern, input, and baseURL if given. 1.3. The URL pattern struct A URL pattern is a struct with the following items: protocol component, a component username component, a component password component, a component hostname component, a component port component, a component pathname component, a component search component, a component hash component, a component A component is a struct with the following items: pattern string, a well formed pattern string regular expression, a RegExp group name list, a list of strings has regexp groups, a boolean 1.4. High-level operations To create a URL pattern given a URLPatternInput input, string or null baseURL, and URLPatternOptions options: Let init be null. If input is a scalar value string then: Set init to the result of running parse a constructor string given input. If baseURL is null and init["protocol"] does not exist, then throw a TypeError. If baseURL is not null, set init["baseURL"] to baseURL. Otherwise: Assert: input is a URLPatternInit. If baseURL is not null, then throw a TypeError. Set init to input. Let processedInit be the result of process a URLPatternInit given init, "pattern", null, null, null, null, null, null, null, and null. For each componentName of « "protocol", "username", "password", "hostname", "port", "pathname", "search", "hash" »: If processedInit[componentName] does not exist, then set processedInit[componentName] to "*". If …