---
title: "URLPattern API"
description: "The URLPattern web API is an URL pattern matching web-platform primitive for JavaScript. Practical notes and code examples."
url: "https://h3manth.com/scribe/urlpattern-api/"
canonical_url: "https://h3manth.com/scribe/urlpattern-api/"
markdown_url: "https://h3manth.com/scribe/blog/urlpattern-api.md"
publishDate: "2021-03-03T00:00:00.000Z"
author: "Hemanth HM"
category: "web"
tags: ["javascript","web-api","urlpattern"]
word_count: 388
reading_time_minutes: 2
x_markdown_tokens: 818
content_signal: "ai-train=yes, search=yes, ai-input=yes"
---

# URLPattern API

> The URLPattern web API is an URL pattern matching web-platform primitive for JavaScript. Practical notes and code examples.

The URLPattern web API is an URL pattern matching web-platform primitive as a generic javascript code. Also helps in controlling service worker to the subset of a site that it owns and maintains.

`URLPattern()` constructor accepts an Object as in input param as in the sample usage and has `test()` and `exec()` methods.

Currently there is a partial implementation of URLPattern available in Chrome Canary under the "Experimental Web Platform features" flag.

## Sample Usage

```javascript
// Takes an Object as a param with the below options
new URLPattern({
  protocol: "https",
  username: "",
  password: "",
  hostname: "example.com",
  port: "",
  pathname: "/foo/bar/:image.jpg",
  search: "(.*)",
  hash: "(.*)",
});
```

```javascript
// Say you want to match the pathname of `/products/(.*)`
const productsPattern = new URLPattern({ "pathname": "/products/(.*)" })
productsPattern.exec({ "pathname": "/products/cars" })

The result would be:
javascript
{
  "hash": { "groups": { "0": "" }, "input": "" },
  "hostname": { "groups": { "0": "" }, "input": "" },
  "input": { "pathname": "/products/cars" },
  "password": { "groups": { "0": "" }, "input": "" },
  "pathname": { "groups": { "0": "cars" }, "input": "/products/cars" },
  "port": { "groups": { "0": "" }, "input": "" },
  "protocol": { "groups": { "0": "" }, "input": "" },
  "search": { "groups": { "0": "" }, "input": "" },
  "username": { "groups": { "0": "" }, "input": "" }
}

## Image Pattern Example
javascript
// imagePattern sample from the spec
const imagePattern = new URLPattern({ pathname: '/*.:imagetype(jpg|png|gif)' });
if (let result = imagePattern.exec(url)) {
  return handleImage(result.pathname.groups['imagetype']);
}

## API Pattern Example
javascript
// apiPattern from the spec
const apiPattern = new URLPattern({ pathname: '/api/:product/:param?' });
if (let result = apiPattern.exec(url)) {
  return handleAPI(result.pathname.groups['product'], result.pathname.groups['param']);
}

## In Service Worker
javascript
// Service worker controlling /cars and everything under /cars/.
// Does not control /carsearch.
navigator.serviceWorker.register("/maps/maps-sw.js", {
  scope: new URLPattern({
    baseURL: self.location,
    pathname: `/cars/*?`,
  }),
});
```

## URLPatternList API

We also have the `URLPatternList` API in the proposals:

```javascript
// Match any URL ending with 'jpg' or 'png'.
const p = new URLPatternList([
  { pathname: "/*.:filetype(jpg)" },
  { pathname: "/*.:filetype(png)" },
]);
```

URLPattern API is highly influenced by [path-to-regexp](https://github.com/pillarjs/path-to-regexp) node module and supports many features including:

- `"*"` wildcards
- named matching groups
- regexp groups
- group modifiers such as `"?"`, `"+"`, and `"*"`

Don't miss read the [Design Document](https://docs.google.com/document/d/17L6b3zlTHtyxQvOAvbK55gQOi5rrJLERwjt_sKXpzqc/edit) for URLPattern API.