Skip to content
Javascript URL mutation library
Branch: gh-pages
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
prettify preparing docs Dec 26, 2011
src chore(build): bumping to version 1.19.1 Feb 10, 2018
test fix(core): properly parse query property (#367) Feb 10, 2018
utils adding utility to read - not in use, but might turn … Nov 3, 2012
.gitignore fix change log issues, add minified versions of last release Aug 6, 2013
.jshintrc adding grunt and jshint Apr 15, 2014 chore(build): bumping to version 1.19.1 Feb 10, 2018
Gruntfile.js fixing jshint issues in tests Apr 15, 2014
about-uris.html Adde dorigin to ascii art diagram Nov 12, 2015
bower.json chore(build): bumping to version 1.19.1 Feb 10, 2018
build.html docs(build): note incompatibility of to module loaders - closes #310 Aug 25, 2016
build.js adding legal stuff to contribution guidelines (requested by May 6, 2014
docs.html chore(build): bumping to version 1.19.0 Oct 1, 2017
jquery-1.7.2.min.js adding test suite for jquery.URI.js and jQuery 1.7.x Nov 11, 2012
jquery-1.8.2.min.js jQuery 1.8 compatibility for jquery.URI.js Nov 2, 2012
screen.css adding note style to docs Mar 8, 2014
uri-template.html feature(templates): adding strict mode for placeholder replacement (#331 Mar 6, 2017



NOTE: The npm package name changed to urijs

I always want to shoot myself in the head when looking at code like the following:

var url = "";
var separator = url.indexOf('?') > -1 ? '&' : '?';

url += separator + encodeURIComponent("foo") + "=" + encodeURIComponent("bar");

Things are looking up with URL and the URL spec but until we can safely rely on that API, have a look at URI.js for a clean and simple API for mutating URIs:

var url = new URI("");
url.addQuery("foo", "bar");

URI.js is here to help with that.

API Example

// mutating URLs
    // ->
    // ->
    // ->
    // ->
    // ->
    // ->
  .query({ foo: "bar", hello: ["world", "mars"] });
    // ->

// cleaning things up
    // -> ?foo=bar&foo=baz

// working with relative paths
    // -> ./baz.html

    // -> ../baz.html
    // -> /foo/bar/baz.html

// URI Templates
URI.expand("/foo/{dir}/{file}", {
  dir: "bar",
  file: "world.html"
// -> /foo/bar/world.html

See the About Page and API Docs for more stuff.

Using URI.js

URI.js (without plugins) has a gzipped weight of about 7KB - if you include all extensions you end up at about 13KB. So unless you need second level domain support and use URI templates, we suggest you don't include them in your build. If you don't need a full featured URI mangler, it may be worth looking into the much smaller parser-only alternatives listed below.

URI.js is available through npm, bower, bowercdn, cdnjs and manually from the build page:

# using bower
bower install uri.js

# using npm
npm install urijs


I guess you'll manage to use the build tool or follow the instructions below to combine and minify the various files into URI.min.js - and I'm fairly certain you know how to <script src=".../URI.min.js"></script> that sucker, too.

Node.js and NPM

Install with npm install urijs or add "urijs" to the dependencies in your package.json.

// load URI.js
var URI = require('urijs');
// load an optional module (e.g. URITemplate)
var URITemplate = require('urijs/src/URITemplate');

    // -> ../baz.html


Clone the URI.js repository or use a package manager to get URI.js into your project.

  paths: {
    urijs: 'where-you-put-uri.js/src'

require(['urijs/URI'], function(URI) {
  console.log("URI.js and dependencies: ", URI("//").is('sld') ? 'loaded' : 'failed');
require(['urijs/URITemplate'], function(URITemplate) {
  console.log("URITemplate.js and dependencies: ", URITemplate._cache ? 'loaded' : 'failed');


See the build tool or use Google Closure Compiler:

// ==ClosureCompiler==
// @compilation_level SIMPLE_OPTIMIZATIONS
// @output_file_name URI.min.js
// @code_url
// @code_url
// @code_url
// @code_url
// @code_url
// ==/ClosureCompiler==


Documents specifying how URLs work:

Informal stuff

How other environments do things

Discussion on Hacker News

Forks / Code-borrow

  • node-dom-urls passy's partial implementation of the W3C URL Spec Draft for Node
  • urlutils cofounders' window.URL constructor for Node


If you don't like URI.js, you may like one of the following libraries. (If yours is not listed, drop me a line…)


URL Manipulation

URL Parsers

URI Template



Contains Code From


URI.js is published under the MIT license. Until version 1.13.2 URI.js was also published under the GPL v3 license - but as this dual-licensing causes more questions than helps anyone, it was dropped with version 1.14.0.


moved to Changelog

You can’t perform that action at this time.