# URLPattern

The `URLPattern` interface of Azion Runtime matches a URL, or parts of a URL, against a pattern. A pattern can hold capture groups that extract parts of the matched URL, such as the ID in a path. For more information, refer to [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) on MDN Web Docs.

> **Note**
>
> Under `azion dev`, `hasRegExpGroups` is `undefined`. The constructor, the other properties, and both methods return the same values locally and deployed.

---

## Constructor

```javascript
new URLPattern(input, baseURL)
```

[`URLPattern()`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/URLPattern) returns a `URLPattern` object built from the pattern and the base URL you pass:

| Parameter | Type             | Description                                                                                                                                                                                       |
| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`   | Object or string | The pattern. An object takes one pattern per URL component, such as `{ pathname: '/users/:id' }`. A string takes the pattern as a URL string, such as `/books/:isbn`, resolved against `baseURL`. |
| `baseURL` | String           | Base URL for a relative pattern string, such as `https://example.com`.                                                                                                                            |

With a base URL, the components the string leaves out come from the base URL: `new URLPattern('/books/:isbn', 'https://example.com')` has the `protocol` `https`, the `hostname` `example.com`, and the `pathname` `/books/:isbn`.

A pattern takes named groups such as `:id`, wildcards (`*`), optional parts in braces such as `http{s}?`, and a regular expression after a group name, such as `:name(\d+)`.

---

## Properties

Each component property returns the pattern of that component, as you passed it. A component you set to an empty string, such as `port`, returns an empty string.

| Property                                                                           | Type    | Description                                                                     |
| ---------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
| `hash`                                                                             | String  | Pattern that matches the hash part of a URL.                                    |
| [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/hostname) | String  | Pattern that matches the hostname part of a URL, such as `{*.}?example.com`.    |
| [`password`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/password) | String  | Pattern that matches the password part of a URL.                                |
| [`pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/pathname) | String  | Pattern that matches the pathname part of a URL, such as `/api/*`.              |
| [`port`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/port)         | String  | Pattern that matches the port part of a URL.                                    |
| [`protocol`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/protocol) | String  | Pattern that matches the protocol part of a URL, such as `http{s}?`.            |
| [`search`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/search)     | String  | Pattern that matches the search part of a URL, such as `q=:q`.                  |
| [`username`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/username) | String  | Pattern that matches the username part of a URL.                                |
| `hasRegExpGroups`                                                                  | Boolean | `true` for a pattern that holds a regular expression group, such as `/a/(\d+)`. |

---

## Methods

| Method                                                                                    | Description                                                                                                                                                                            |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`pattern.exec(input)`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/exec) | Returns an object with the matched parts of the URL, or `null` when the URL does not match. Each component of the result, such as `pathname`, carries the captured values in `groups`. |
| [`pattern.test(input)`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/test) | Returns `true` when the URL matches the pattern, and `false` when it does not.                                                                                                         |

Both methods take a URL string. `exec()` also takes an object of URL components: for the pattern `{ pathname: '/files/:name(\\d+).:ext' }`, `exec({ pathname: '/files/12.png' })` returns the `pathname` groups `{ name: '12', ext: 'png' }`.

---

## Example

This handler matches two URLs against a pathname pattern with a named group, then returns the results of `test()` and `exec()` with `Response.json()`:

```javascript
export default {
  async fetch(request, env, ctx) {
    const pattern = new URLPattern({ pathname: '/users/:id' });
    return Response.json({
      test: pattern.test('https://example.com/users/42'),
      group: pattern.exec('https://example.com/users/42')?.pathname.groups,
      miss: pattern.exec('https://example.com/posts/1'),
    });
  },
};
```

The function returns these values. The `id` group captures `42`, and `exec()` returns `null` for the URL that does not match:

```json
{
 "test": true,
 "group": {
  "id": "42"
 },
 "miss": null
}
```

---

## Related resources

- [Request](/en/documentation/devtools/runtime/api-reference/request.md): The incoming request, whose URL a function can match against a pattern.
- [Response](/en/documentation/devtools/runtime/api-reference/response.md): How a function builds the response it returns, as the example does with `Response.json()`.
- [Handlers](/en/documentation/devtools/runtime/api-reference/handlers.md): The handler shapes a function exports to receive requests.
- [Web APIs](/en/documentation/devtools/runtime/api-reference/javascript.md): The other Web APIs that Azion Runtime supports.