What is url-pattern?
The url-pattern npm package is a utility for matching URL patterns and extracting parameters from URLs. It is useful for routing in web applications, where you need to determine which code to execute based on the URL path.
What are url-pattern's main functionalities?
Pattern Matching
This feature allows you to define URL patterns and match them against actual URLs. The example demonstrates how to create a pattern for user IDs and match it against a URL, extracting the user ID as a parameter.
const UrlPattern = require('url-pattern');
const pattern = new UrlPattern('/users/:id');
const match = pattern.match('/users/123');
console.log(match); // { id: '123' }
Reverse URL Generation
This feature allows you to generate URLs from a pattern and a set of parameters. The example shows how to create a URL for a specific user ID using the pattern.
const UrlPattern = require('url-pattern');
const pattern = new UrlPattern('/users/:id');
const url = pattern.stringify({ id: '123' });
console.log(url); // '/users/123'
Wildcard Matching
This feature allows you to use wildcards in your URL patterns to match any sequence of characters. The example demonstrates how to match any file path under the '/files' directory.
const UrlPattern = require('url-pattern');
const pattern = new UrlPattern('/files/*');
const match = pattern.match('/files/images/photo.jpg');
console.log(match); // { _: 'images/photo.jpg' }
Other packages similar to url-pattern
path-to-regexp
The path-to-regexp package is another utility for matching URL patterns and extracting parameters. It is more flexible and powerful than url-pattern, supporting advanced pattern matching features like optional parameters and custom parameter patterns.
route-parser
The route-parser package provides similar functionality for defining and matching URL patterns. It is simpler and more lightweight compared to url-pattern, making it a good choice for smaller projects or when you need a minimal solution.
url-patterns
The url-patterns package is another alternative for URL pattern matching and parameter extraction. It offers a similar API to url-pattern but includes additional features like query string parsing and more advanced pattern matching capabilities.
url-pattern

url-pattern is easy pattern matching and segment extraction for
urls, domains, filepaths and any string composed of segments joined
by a separator character
check out passage if you are looking for simple composable routing that builds on top of url-pattern
npm install url-pattern
require with commonjs:
var Pattern = require('url-pattern');
lib/url-pattern.js can be used in the browser.
it supports AMD as well.
match urls or filepaths
make pattern from string
var pattern = new Pattern('/users/:id');
the default separator is /
. you can pass a custom separator
as the second argument.
match pattern against url
match returns the extracted parameters or null
if there was no match:
pattern.match('/users/5');
pattern.match('/projects/5');
make pattern from regex
var regexPattern = new Pattern(/\/test\/(.*)/);
match regex pattern against url
if the pattern was created from a regex an array of the captured groups is returned on match:
regexPattern.match('/test/users');
regexPattern.match('/users/test');
make wildcard pattern from string
var wildcardPattern = new Pattern('*/users/:id/*');
match wildcard pattern against url
wildcard matches are collected in the _
property:
wildcardPattern.match('/api/v1/users/10/followers/20');
make optional pattern from string
var optionalPattern = new Pattern('(/)users(/:foo)/bar(/*)');
match optional pattern against url
optional matches are stored in the corresponding property, if they exist.
optionalPattern.match('users/bar');
optionalPattern.match('/users/bar');
optionalPattern.match('/users/biff/bar');
optionalPattern.match('/users/biff/bar/beep/boop');
match domains
make pattern from string
var pattern = new Pattern(':sub.google.com', '.');
the default separator is /
. you can pass a custom separator
as the second argument to Pattern
.
match pattern against domain
match returns the extracted parameters or null
if there was no match:
pattern.match('www.google.com');
pattern.match('www.google.io');
make pattern from regex
var regexPattern = new Pattern(/example\.(.*)/);
match regex pattern against domain
if the pattern was created from a regex an array of the captured groups is returned on match:
regexPattern.match('example.com');
regexPattern.match('google.com');
make wildcard pattern from string
var wildcardPattern = new Pattern('*.:sub.google.*');
match wildcard pattern against url
wildcard matches are collected in the _
property:
wildcardPattern.match('subsub.www.google.com');
changelog
0.7
instead of
var urlPattern = require('url-pattern');
var pattern = urlPattern.newPattern('/example');
now use
var Pattern = require('url-pattern');
var pattern = new Pattern('/example');
contribution
TLDR: bugfixes, issues and discussion are always welcome.
ask me before implementing new features.
i will happily merge pull requests that fix bugs with reasonable code.
i will only merge pull requests that modify/add functionality
if the changes align with my goals for this package
and only if the changes are well written, documented and tested.
communicate: write an issue to start a discussion
before writing code that may or may not get merged.
todo
- https://github.com/snd/url-pattern/issues/6
- parse string into array of objects describing structure
- constant
- binding
- wildcard
- optional
- multiple occurences of the same name are collected into an array
- this elegantly normalizes * and :
- binding parsing is flexible and has a start and end regex
- default:
:
and `[^a-zA-Z0-9]
- custom:
#{
and }
- test that empty names are not allowed
- browser tests