Generic Sinatra/Backbone style route pattern matching



The most important feature of this library is that it does pattern matching and nothing, nothing more.

Other features are:

  • Environment, framework and tool agnostic. Works in both Node.js and the browser. No jQuery, Express etc. needed.
  • Match against the path, search (query string) and the hash part of a location
  • Define patterns for matching only against the parts of the location you are interested in
  • Match against a location and capture named parameters, query string, etc.
  • Well tested.

In other words, you could use this library to support routing in your app or framework.

var pattern = RoutePattern.fromString("/planets/:planet")
pattern.matches("/planets/earth?fruit=apple#bookmark") // true 
var pattern = RoutePattern.fromString("?foo=:foo&fruit=:fruit")
pattern.matches("/hello/world?foo=bar&fruit=apple") // true 
pattern.matches("/ignore/what/is/here?fruit=apple&foo=bar") // true 

Path-like patterns can be used in the hash part of the route string too.

var pattern = RoutePattern.fromString("#/chapters/:chapter")
pattern.matches("#/chapters/5") // true 
pattern.matches("/books/3432?display=full#/chapters/2") // true 

By default, query string routes will match only when all speficied parameters are present in the matched location string, and they are the only query parameters in the location string. Thus, the following statement will be false:

RoutePattern.fromString("?foo=:foo").matches("?foo=bar&baz=qux") // false 

To specify that other query parameters should be allowed, add a single wildcard to the route string:

RoutePattern.fromString("?foo=:foo&*").matches("?foo=bar&baz=qux") // true 

Wildcards can also be used in the path to ignore whatever is in the place of the *

var pattern = RoutePattern.fromString("*/planets/:planet/*")
pattern.matches("/some/root/path/planets/earth/facts/about/this/planet") // true 
var pattern = RoutePattern.fromString("/hello/:planet?foo=:foo&fruit=:fruit#:section")
// Returns: 
  params: ["bar", "apple"],
  namedParams: { planet: "earth", foo: "bar", fruit: "apple" }
  pathParams: { planet: "world" }
  queryParams: { foo: "bar", fruit: "apple" }
  hashParams: { section: "chapter2" }

Note: namedParams is a merge of pathParams, queryParams and hashParams.

Wildcards in the route string will ignore whatever is in the place of the *

var pattern = RoutePattern.fromString("*/planets/:planet/*")
pattern.match("/some/root/path/planets/earth/facts/about/this/planet") // true 
// Returns: 
  params: ["earth"],
  namedParams: {
    planet: "earth"

Splat parameters is like wildcards, only that they will capture the value of the identifier that comes after the *

var pattern = RoutePattern.fromString("*before/planets/:planet/*after")
// Returns: 
  params: ["some/root/path","earth","facts/about/this/planet"],
  namedParams: {
    before: "some/root/path",
    planet: "earth",

Getting started

  1. Install with npm: npm install route-pattern
  2. From your .js file: var RoutePattern = require("route-pattern");

This module works in all major browsers, including IE 8-10. However, it makes use of ECMAScript 5 features, so in order to make it work on legacy browsers, you need to include a ECMAScript 5 shim, like the es5-shim.

Download latest version:

When included with a <script> tag, it it will expose the RoutePattern class as a global variable.


Compiles a route string and returns a RoutePattern instance.

Constructor. Usually its better to use RoutePattern.fromString(routeString) instead of using the constructor directly.

Matches a location string against the pattern and returns captured values (i.e. params, namedParams, queryParams, hashParams and pathParams)

Tests whether the pattern matches a given location string


RoutePattern.fromString("/foo/:bar").matches("/foo/bar/baz") // false
RoutePattern.fromString("/foo/:bar").matches("/foo/bar") // true

Future work:

  • Allow pattern matching against the full url (i.e. scheme, domain, port in addition to the currently supported parts of the url). Useful where same script resides on multiple domains.


  • Rename RegexPattern => RegExpPattern.
  • Make all the Pattern classes' match() methods return null if there are no match.