Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท path, os and url

The Node.js URLPattern class

Reference for URLPattern in Node.js: match URLs against patterns with named groups, wildcards and optional parts, and read captured values.

URLPattern is a global class that matches URLs against a pattern, much like a router does. A pattern describes the pathname (and optionally protocol, hostname, query and more) using named groups such as :id, wildcards *, optional parts {...}? and modifiers like ?, + and *.

Calling pattern.test(url) answers yes or no, and pattern.exec(url) returns the captured groups for every URL component. It follows the web platform standard, so the same patterns work in browsers that support it and in service workers. In Node.js it is a global in current versions (Node.js 24 LTS has it).

NODE
const pattern = new URLPattern({ pathname: "/users/:id" });
console.log(pattern.exec("http://localhost/users/42").pathname.groups.id);

Try it

Node.js Named groups and testing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Wildcards, optional parts and relative patterns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new URLPattern(input?: string | URLPatternInit, baseURL?: string, options?: { ignoreCase?: boolean })
pattern.test(input?: string | URLPatternInit, baseURL?: string): boolean
pattern.exec(input?: string | URLPatternInit, baseURL?: string): URLPatternResult | null
Name Description
input A pattern string, or an object with any of protocol, username, password, hostname, port, pathname, search, hash and baseURL. Missing components match anything.
baseURL Base for relative pattern strings or relative URLs.
options.ignoreCase Case-insensitive matching (the default is case-sensitive).

Returns: test() gives a boolean. exec() gives null on no match, or an object with inputs and one entry for each component (pathname, search, hostname, ...) holding { input, groups }.

Properties: read-only strings for each component pattern (pattern.pathname, pattern.protocol, ...) and hasRegExpGroups.

Errors: a TypeError is thrown when the pattern syntax is invalid.

Usage notes

  • Unnamed groups are numbered. A wildcard * appears in groups as "0", "1" and so on.
  • A missing optional part is undefined in groups, as for month in the second example.
  • Only the components you give are compared. { pathname: "/a" } matches any scheme, host and query. Add protocol and hostname for strict routing.
  • Trailing slashes matter. /books/:id does not match /books/7/; write /books/:id{/}? to allow both.
  • Matching is on the URL after normalization, so %2F and case in the host behave as the URL parser dictates.
  • Group values are percent-encoded text from the URL; decode with decodeURIComponent() if needed.
  • Check availability on old runtimes. Node.js 22 and older do not expose it as a global.
  • Compile patterns once and reuse them; constructing a pattern for every request is wasteful.