URLPattern

URLPattern lets you match URLs — or individual components of them — against patterns with wildcards and named groups. The syntax is inspired by path-to-regexp, the same library Express uses for its route definitions.

Browser support: Newly available Baseline as of late 2025 (Chrome/Edge 95+, Safari 16.4+, Firefox 142+, which shipped in September 2025). Per our requirement engineering guidance, prefer it for B2B or controlled-browser projects. For public B2C apps, ship the official urlpattern-polyfill package or fall back to manual parsing.

Use cases

• Client-side routing in SPAs
• Service Worker request interception (matching routes inside a fetch handler)
• Declarative web app manifest scope_extensions
• Deep-link and redirect rules
• Validating and extracting parameters from incoming URLs

Example — basic matching

const pattern = new URLPattern("https://example.com/books/:id");

pattern.test("https://example.com/books/42"); // true

const result = pattern.exec("https://example.com/books/42");
console.log(result.pathname.groups); // { id: "42" }

Example — pattern syntax

Patterns can include named groups (:name), wildcards (*), optional segments (?), and regex constraints. You can also use the init-object form to match individual URL components:

// String form: named group + regex constraint + optional + wildcard
new URLPattern("/users/:id(\\d+)/posts/:slug?/*", "https://example.com");

// Init-object form: only the components you specify are constrained
new URLPattern({ pathname: "/api/:resource/:id" });

Example — Service Worker routing

const bookRoute = new URLPattern({ pathname: "/books/:id" });

self.addEventListener("fetch", (event) => {
  const match = bookRoute.exec(event.request.url);
  if (match) {
    const { id } = match.pathname.groups;
    event.respondWith(getBookResponse(id));
  }
});

Comparison with regex on URL.pathname

Feature	URLPattern	Regex on URL.pathname
Readability	High — declarative	Low — escape-heavy
Named groups	Built-in	Manual (named capture groups)
Multi-component matching	Yes (protocol/host/path/search/hash in one pattern)	Path only — other components handled separately
Browser-native	Yes	Yes
Learning curve	path-to-regexp syntax	Regex syntax

When to use

Reach for URLPattern when you need declarative URL matching — routing, service workers, or rule-based redirects — and you control the browser (or you're shipping the polyfill). For a one-off check on a single URL, parsing with new URL(...) and a small regex on pathname is still perfectly fine.

Limitations

• Not yet Widely available Baseline — needs the polyfill for broad public sites
• Pattern syntax has subtle differences from path-to-regexp v6 (e.g. unnamed groups, escaping rules)
• Each URL component (protocol/username/password/hostname/port/pathname/search/hash) is matched separately; unspecified components default to wildcards relative to a base URL
• Case sensitivity differs by component (e.g. hostname is case-insensitive, pathname is not)