parseUri 1.2: Split URLs in JavaScript

Edit (2024): parseUri has had a major update and is now available on GitHub and npm

I've just updated parseUri. If you haven't seen the older version, parseUri is a function which splits any well-formed URI into its parts, all of which are optional. Its combination of accuracy, flexibility, and brevity is unrivaled.

Highlights:

  • Comprehensively splits URIs, including splitting the query string into key/value pairs. (Enhanced)
  • Two parsing modes: loose and strict. (New)
  • Easy to use (returns an object, so you can do, e.g., parseUri(uri).anchor).
  • Offers convenient, pre-concatenated components (path = directory and file; authority = userInfo, host, and port; etc.)
  • Change the default names of URI parts without editing the function, by updating parseUri.options.key. (New)
  • Exceptionally lightweight (1 KB before minification or gzipping).
  • Released under the MIT License.

Details:

Older versions of this function used what's now called loose parsing mode (which is still the default in this version). Loose mode deviates slightly from the official generic URI spec (RFC 3986), but by doing so allows the function to split URIs in a way that most end users would expect intuitively. However, the finer details of loose mode preclude it from properly handling relative paths which do not start from root (e.g., "../file.html" or "dir/file.html"). On the other hand, strict mode attempts to split URIs according to RFC 3986. Specifically, in loose mode, directories don't need to end with a slash (e.g., the "dir" in "/dir?query" is treated as a directory rather than a file name), and the URI can start with an authority without being preceded by "//" (which means that the "yahoo.com" in "yahoo.com/search/" is treated as the host, rather than part of the directory path).

Since I've assumed that most developers will consistently want to use one mode or the other, the parsing mode is not specified as an argument when running parseUri, but rather as a property of the parseUri function itself. Simply run the following line of code to switch to strict mode:

parseUri.options.strictMode = true;

From that point forward, parseUri will work in strict mode (until you turn it back off).

The code:

// parseUri 1.2.2
// (c) Steven Levithan <stevenlevithan.com>
// MIT License

function parseUri (str) {
	var	o   = parseUri.options,
		m   = o.parser[o.strictMode ? "strict" : "loose"].exec(str),
		uri = {},
		i   = 14;

	while (i--) uri[o.key[i]] = m[i] || "";

	uri[o.q.name] = {};
	uri[o.key[12]].replace(o.q.parser, function ($0, $1, $2) {
		if ($1) uri[o.q.name][$1] = $2;
	});

	return uri;
};

parseUri.options = {
	strictMode: false,
	key: ["source","protocol","authority","userInfo","user","password","host","port","relative","path","directory","file","query","anchor"],
	q:   {
		name:   "queryKey",
		parser: /(?:^|&)([^&=]*)=?([^&]*)/g
	},
	parser: {
		strict: /^(?:([^:\/?#]+):)?(?:\/\/((?:(([^:@]*)(?::([^:@]*))?)?@)?([^:\/?#]*)(?::(\d*))?))?((((?:[^?#\/]*\/)*)([^?#]*))(?:\?([^#]*))?(?:#(.*))?)/,
		loose:  /^(?:(?![^:@]+:[^:@\/]*@)([^:\/?#.]+):)?(?:\/\/)?((?:(([^:@]*)(?::([^:@]*))?)?@)?([^:\/?#]*)(?::(\d*))?)(((\/(?:[^?#](?![^?#\/]*\.[^?#\/.]+(?:[?#]|$)))*\/?)?([^?#\/]*))(?:\?([^#]*))?(?:#(.*))?)/
	}
};

You can download it here.

parseUri has no dependencies, and has been tested in IE 5.5–7, Firefox 2.0.0.4, Opera 9.21, Safari 3.0.1 beta for Windows, and Swift 0.2.

177 thoughts on “parseUri 1.2: Split URLs in JavaScript”

  1. Thanks again! I’ve made your suggested change and things are still working well.

    I look forward to next version.

    -Ruby

  2. I did a PHP port of this amazing function.
    I added 2 features.
    Hope it could be useful !!
    Have fun !

    LudoO

    <?php
    /*
    	PhpParseUri 1.0
    
    	PHP Port of parseUri 1.2.1
    		- added file:///
    		- added : windows drive detection
    		
    	PHP Port: LudoO 2009 <pitaso.com>
    
    	Original JS : (c) 2007 Steven Levithan <stevenlevithan.com>	MIT License
    	
    */
    function parseUri($str) {
    	global $parseUri_options;
    	$o   = $parseUri_options;
    	$r   = $o['parser'][$o['strictMode'] ? "strict" : "loose"];
    	preg_match($r, $str, $m);
    	$uri = array();
    	$i   = 15;
    
    	while ($i--) $uri[$o['key'][$i]] = $m[$i];
    
    	$uri[$o['q']['name']] = array();
    	preg_match_all($o['q']['parser'], $uri[$o['key'][13]], $n);
    	if ($n && sizeof($n)>0){
    		for ($i = 1; $i <= sizeof($n); $i++) {
    			$v =$n[$i];
    			if ($v) $uri[$o['q']['name']][$v[0]] = $v[1];
    		}
    	}
    	return $uri;
    };
    $parseUri_options = array(
    	strictMode => false,
    	key => array("source","protocol","authority","userInfo","user","password","host","port","relative","path","drive","directory","file","query","anchor"),
    	q =>   array(
    		name =>   "queryKey",
    		parser => '/(?:^|&)([^&=]*)=?([^&]*)/'
    	),
    	parser => array(
    		strict => '/^(?:([^:\/?#]+):)?(?:\/\/\/?((?:(([^:@]*):?([^:@]*))?@)?([^:\/?#]*)(?::(\d*))?))?(((?:\/(\w:))?((?:[^?#\/]*\/)*)([^?#]*))(?:\?([^#]*))?(?:#(.*))?)/',
    		loose =>  '/^(?:(?![^:@]+:[^:@\/]*@)([^:\/?#.]+):)?(?:\/\/\/?)?((?:(([^:@]*):?([^:@]*))?@)?([^:\/?#]*)(?::(\d*))?)(((?:\/(\w:))?(\/(?:[^?#](?![^?#\/]*\.[^?#\/.]+(?:[?#]|$)))*\/?)?([^?#\/]*))(?:\?([^#]*))?(?:#(.*))?)/'
    	)
    );
    ?>
    
  3. Thanks for this! One small issue: if a URL has multiple instances of the same parameter name (as can occur if multiple checkboxes are checked on a form) then queryKey will only contain the last value associated with this name. So if the query string is

    x=a&x=b

    then queryKey.x ends up as ‘b’, and the x=a pair is lost. It might be nicer if, say, an array of strings rather than a single string was assigned to the corresponding element of queryKey in such cases.

  4. I was using your parseUri class in JavaScript and noticed that the path “file.ext” is not considered a file by your script. It looks like it is expecting a preceding slash. I don’t know if this is a bug or just a feature that was left out. My work around was just some extra conditioning tests. Nice work on this class and thanks for posting it.

  5. @Mike, in non-strict mode, a URL starting with a filename (i.e., no preceding slash) is treated as a host, for reasons explained elsewhere. Switch to strict mode and you should be OK.

  6. @Scott, that URL is invalid. The @ sign is supposed to be URL encoded as “%40”–if you make this change, parseUri will handle it fine.

    FYI, you’re not the first person to request different handling for invalid uses of “@” (see Anup Chatterjee and Andrew Zitnay’s comments here), so perhaps it’s worth looking at changes to “loose” parsing mode, at least, in future versions of this script.

  7. Awesome code. Ultimate Regex.
    I found this letter >a< knocking around, which i present to you for insertion into the appropriate position in your surname.

  8. Sorry, strict mode seems to address that, but the jQuery plugin doesn’t seem to use strict mode properly. I will investigate on that end. Thanks for the great parser!

  9. @James, lol.

    @Neeta, parseUri returns the correct result. Everything after the # sign is the URI fragment (aka anchor). There is no query part.

  10. Dear Mr. Levithan, hello Steven,

    Thanks a lot for your javascript magic.

    I have a feature suggestion if that’s appropriate. Since parseUri is returning an object, would it be a decent idea to add a method which would reassemble the URL back to a string from its parts?

    That could be quite handy for actually manipulating URL’s. One could then alter parts of the URL (add or modify parts of the query, the user information, whatsoever) without doing any regexp magic in their own code.

    Cheers,

    Rien

  11. @Rien,

    there is a source property in the returned object that contains the original string.

    Thanks Steven for this script, I use it together with a Punycode encoder on some proxies to support IDN domains and parseUri has helped a lot keeping the code small.

  12. Very nice! It does break on the URL http://www.blahblah.com/@foo/bar as Leechael noted, but still, for how simple it is, I am duly impressed. My MUCH longer version of a strict RFC-3986 parser written in C is over at github (http://github.com/ajrisi/fsm). I didn’t use regex like you, I used a hand-rolled finite state machine. The output isn’t quite as readable as yours either. Still, might be worth something to someone!

  13. Actually, the ‘@’ sign is a perfectly valid character for the path, query and fragment portions of a URI according to RFC3986 and does not need to be encoded as ‘%40’.

    Look at the ABNF definition for ‘pchar’ in Appendix A of RFC3986.

  14. Hi,

    I’ve taken Robert’s idea of creating an array of values for parameters that were given multiple times. Unlike him, I did so without using a third party library. Here’s the code if anyone’s interested:

    Replace the line

    if ($1) uri[o.q.name][$1] = $2;

    with

    if ($1) {
    if (uri[o.q.name][$1] === undefined) {
    uri[o.q.name][$1] = $2;
    } else if (typeof uri[o.q.name][$1] === ‘[object Array]’) {
    uri[o.q.name][$1].push($2);
    } else if (typeof uri[o.q.name][$1] === ‘string’) {
    uri[o.q.name][$1] = [ uri[o.q.name][$1], $2];
    }
    }

  15. Newbie question.
    We have a job application form that uses the document.referrer to identify which job they are applying for. And, I want to add this info into the subject line of the email sent to our hr person. I came across your code that will parse the url.
    how do I take what your parser produces so I can add it to the subject line?

  16. Hi,

    I’ve enhanced the loose mode a bit to support and tokenize literal IPv4 and IPv6 addresses as well as splitting an FQDN into hostname and domain.

    Thanks
    Norbert

    String.prototype.parseUri = function() {
    var o = String.prototype.parseUri.options;
    var m = o.parser.ipv6.exec(this);
    var uri = {};
    var i = 18;
    while (i–)
    uri[o.key[i]] = m[i] || “”;

    uri[o.q.name] = {};
    uri[o.key[16]].replace(o.q.parser, function($0, $1, $2) {
    if ($1)
    uri[o.q.name][$1] = $2;
    });

    if (uri.ipv4 != “”) {
    uri.ip = uri.ipv4;
    }
    else
    if (uri.ipv6 != “”) {
    uri.ip = uri.ipv6;
    }

    return uri;
    };

    String.prototype.parseUri.options = {
    // strictMode : false,
    key : [ “source”, “protocol”, “authority”, “userInfo”, “user”, “password”,
    “host”, “ipv4”, “ipv6”, “basename”, “domain”, “port”, “relative”,
    “path”, “directory”, “file”, “query”, “anchor” ],
    q : {
    name : “queryKey”,
    parser : /(?:^|&)([^&=]*)=?([^&]*)/g
    },
    parser : {
    ipv6 : /^(?:(?![^:@]+:[^:@\/]*@)([^[:\/?#.]+):)?(?:\/\/)?((?:(([^:@]*)(?::([^:@]*))?)?@)?((?:(\d+\.\d+\.\d+\.\d+)|\[([a-fA-F0-9:]+)\]|([^.:\/?#]*))(?:\.([^:\/?#]*))?)(?::(\d*))?)(((\/(?:[^?#](?![^?#\/]*\.[^?#\/.]+(?:[?#]|$)))*\/?)?([^?#\/]*))(?:\?([^#]*))?(?:#(.*))?)/
    }
    };

  17. Hi, great piece of code.

    BTW, is there any function for doing the opposite operation? (I mean getting the string URL from the parsed one).

    It could be useful when you need to change some URL params on the query string or any part of the URL. (that’s inded what I need to do on a CMS I’m building: http://code.google.com/p/yupp-cms/)

    Thanks a lot!

  18. Steve,

    FYI- I used a Domino function to grab from $0 everything to the right of the = sign instead of using $2 and it now returns the correct values. Thanks again for contributing. Great code.

  19. Hi author i would like to ask how could I use this code as javascipt that could display incoming search term to my site. Its like when someone searches in google and arrives to my site, the url of the referrer is parsed and displayed in my website as ” incoming search term (keyword)” ? any suggestion about making it in javascipt?

  20. Hi Steven,

    As some others have pointed out already your code doesn’t work for urls with a @ in the path or query part.

    For example http://www.adperium.com/campaigns/example@example.com/93f92b1c will return example.com as the host.

    According to rfc 3986 section-3.3, @ is a valid path character.

    Since adblock for chrome uses your code to parse urls it currently blocks parts of sites that shouldn’t be blocked.

  21. This was just what I wanted except: I’m passing some javascript code with spaces and funny chars in the string. So I wrote a little extension to decode these:

    So I replaced the line:
    if ($1) uri[o.q.name][$1] = $2
    with
    if ($1) uri[o.q.name][$1] = $2.replace(o.q.decode, function ($3, $4) {
    return ($4) ? String.fromCharCode (parseInt($4, 16)) : ” “;
    });

    and added this to the q structure.
    decode: /(?:\+)|(?:%(..))/g

Leave a Reply

Your email address will not be published. Required fields are marked *