Status: Draft
Version: 1.4

dojo.hash provides methods for monitoring and updating the hash in the browser URL as well as back/forward support and bookmarkability for dynamic web applications.


HTML5 defines an onhashchange event that fires when the value of the hash segment of the URL changes.

dojo.hash uses the native onhashchange event if the browser supports it, and emulates this support for older browsers using a polling loop.


To use dojo.hash to listen for hash changes:

  1. Add the appropriate require statement:

  2. Subscribe to /dojo/hashchange event:

    dojo.subscribe("/dojo/hashchange", context, callback);

    Whenever the hash changes, your callback will be called with the new hash value passed as the first parameter.

Manipulating the URL

Dojo.hash() provides mechanisms for getting and setting the URL's hash value.


To update the hash value, call dojo.hash with the new hash value as the first parameter. This will create a new entry in the back history and will notify any /dojo/hashchange subscribers:


To update the hash without creating a new entry in the back history, pass true as the second (replace) param. This will update the URL to the new hash, and will replace the current history state:



dojo.hash() with no parameters returns the current hash value.

var hashValue = dojo.hash();


  1. Subscribe to the hashchange event:

    dojo.subscribe("/dojo/hashchange", context, callback);
  2. Set the hash using query notation:

    function() {
        var obj = {
            firstParam: true,
            secondParam: false
Hash: #firstParam=true&secondParam=false
  1. Parse this hash and add a parameter using query notation:

Initial hash: #firstParam=true&secondParam=false

function updateHash() {
    var obj = dojo.queryToObject(dojo.hash());  //get
    obj.someNewParam = true;
    dojo.hash(dojo.objectToQuery(obj));  //set

End hash: #firstParam=true&secondParam=false&someNewParam=true

  1. React to hashchange event (hash passed to callback as first param):

    function callback(hash) {
        //hashchange event!
        var obj = dojo.queryToObject(hash);
        if (obj.firstParam) {
             // do something
  2. Get and set the hash using slash notation:

Initial hash: #/firstSegment/secondSegment

function updateHash() {
    var obj = dojo.hash().split("/");

End hash: #/firstSegment/secondSegment/trailingSegment


Customizing the polling loop frequency

For browsers that don't support the onhashchange event natively, a polling loops monitors the URL for changes. The default duration of this polling loop is 100 ms. To customize this value, add "hashPollFrequency" to djConfig.

djConfig = {
    hashPollFrequency: 200

dojo.hash automatically decodes the hash value when you use it as a getter. As a setter, it is up to the consumer to properly encode the pieces of input that should be encoded. Anything with HTML encoding (i.e. &) must be encoded with encodeURIComponent before being passed into dojo.hash due to discrepancies between browsers (Firefox decodes HTML encoding automatically before setting the URL, IE does not).

dojo.hash(encodeURIComponent("hash with & HTML encoding"))

dojo/hash (last edited 2009-09-15 17:54:01 by retchless)