URLPattern

interface

interface URLPattern

The URLPattern API provides a web platform primitive for matching URLs based on a convenient pattern syntax.

Common use cases for URLPattern include:

  • Building routers for web applications
  • Pattern-matching URLs for middleware
  • Extracting parameters from URL paths
  • URL-based feature toggles
  • Routing in serverless and edge functions

The syntax is based on path-to-regexp, supporting wildcards, named capture groups, regular groups, and group modifiers - similar to Express.js route patterns.

Example

// Basic routing with URLPattern (similar to Express.js)
const routes = [
  new URLPattern({ pathname: "/users" }),
  new URLPattern({ pathname: "/users/:id" }),
  new URLPattern({ pathname: "/products/:category/:id?" }),
];

// Check incoming request against routes
function handleRequest(req: Request) {
  const url = new URL(req.url);

  for (const route of routes) {
    const match = route.exec(url);
    if (match) {
      // Extract parameters from the URL
      const params = match.pathname.groups;
      return new Response(`Matched: ${JSON.stringify(params)}`);
    }
  }

  return new Response("Not found", { status: 404 });
}

Example

// Matching different URL parts
const apiPattern = new URLPattern({
  protocol: "https",
  hostname: "api.example.com",
  pathname: "/v:version/:resource/:id?",
  search: "*", // Match any query string
});

const match = apiPattern.exec("https://api.example.com/v1/users/123?format=json");
if (match) {
  console.log(match.pathname.groups.version); // "1"
  console.log(match.pathname.groups.resource); // "users"
  console.log(match.pathname.groups.id); // "123"
}

variable

var URLPattern: { … }

The URLPattern API provides a web platform primitive for matching URLs based on a convenient pattern syntax.

The syntax is based on path-to-regexp. Wildcards, named capture groups, regular groups, and group modifiers are all supported.

// Specify the pattern as structured data.
const pattern = new URLPattern({ pathname: "/users/:user" });
const match = pattern.exec("https://blog.example.com/users/joe");
console.log(match.pathname.groups.user); // joe
// Specify a fully qualified string pattern.
const pattern = new URLPattern("https://example.com/books/:id");
console.log(pattern.test("https://example.com/books/123")); // true
console.log(pattern.test("https://deno.land/books/123")); // false
// Specify a relative string pattern with a base URL.
const pattern = new URLPattern("/article/:id", "https://blog.example.com");
console.log(pattern.test("https://blog.example.com/article")); // false
console.log(pattern.test("https://blog.example.com/article/123")); // true

Constructors

constructor

new URLPattern(input: URLPatternInput, baseURL: string, options?: URLPatternOptions): URLPattern
new URLPattern(input?: URLPatternInput, options?: URLPatternOptions): URLPattern

Properties

protocol

readonly protocol: string

The pattern string for the protocol.

username

readonly username: string

The pattern string for the username.

password

readonly password: string

The pattern string for the password.

hostname

readonly hostname: string

The pattern string for the hostname.

port

readonly port: string

The pattern string for the port.

pathname

readonly pathname: string

The pattern string for the pathname.

readonly search: string

The pattern string for the search.

hash

readonly hash: string

The pattern string for the hash.

hasRegExpGroups

readonly hasRegExpGroups: boolean

Whether or not any of the specified groups use regexp groups.

prototype

readonly prototype: URLPattern

Methods

test

test(input: URLPatternInput, baseURL?: string): boolean

Test if the given input matches the stored pattern.

The input can either be provided as an absolute URL string with an optional base, relative URL string with a required base, or as individual components in the form of an URLPatternInit object.

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

// Test an absolute url string.
console.log(pattern.test("https://example.com/books/123")); // true

// Test a relative url with a base.
console.log(pattern.test("/books/123", "https://example.com")); // true

// Test an object of url components.
console.log(pattern.test({ pathname: "/books/123" })); // true

exec

exec(input: URLPatternInput, baseURL?: string): URLPatternResult | null

Match the given input against the stored pattern.

The input can either be provided as an absolute URL string with an optional base, relative URL string with a required base, or as individual components in the form of an URLPatternInit object.

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

// Match an absolute url string.
let match = pattern.exec("https://example.com/books/123");
console.log(match.pathname.groups.id); // 123

// Match a relative url with a base.
match = pattern.exec("/books/123", "https://example.com");
console.log(match.pathname.groups.id); // 123

// Match an object of url components.
match = pattern.exec({ pathname: "/books/123" });
console.log(match.pathname.groups.id); // 123