Skip to content
Application state in query string
JavaScript HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

query-state Build Status

Application state in query string.



Grab it from npm and use with your favorite bundler:

npm install query-state --save

Or download from CDN:

<script src=''></script>

If you downloaded from CDN the library will be available under queryState global name.

// create a new query state instance
var qs = queryState();

// get current application state from the hash string:
var appState = qs.get();

// you can also monitor for changes in the query string:
qs.onChange(function(appState) {
  // prints new application state on each hash update
  console.log('app state changed!', appState);

// If you want to set a new value in the app state:
qs.set('answer', 42);

// Now the query string will have `answer=42` part in it.
console.log(window.location.hash.indexOf('answer=42')) // prints value > 0.

// You can also set multiple values at once:
  name: 'Haddaway',
  song: 'What is love?'

// NOTE: The call above merges new properties. It appends two new properties to 
// the current query string


If you want to initialize app state with default values, you can pass them into query state function:

// this will set query string to `answer=42`, unless it already has key called
// "answer". In which case query string's value will take precedence.
var qs = queryState({
  answer: 42

type limitations

This is a very simple module that currently does not support nested objects. I.e. you cannot set application state to {foo: {bar: 42}}. If you need this behavior, most likely this module is not for you.

We do support primitive types serialization/deserialization:

  • Numbers
  • Dates
  • Strings

Sharing between modules (singleton)

If you are using a bundler (e.g. browserify or webpack), its often desirable to have just one instance of the application state, shared between files. Normally this is accomplished via singleton pattern. The library exposes singleton instance for your convenience:

// fileA.js
var stateInFileA = queryState.instance();

// fileB.js
var stateInFileB = queryState.instance();

// Both `stateInFileA` and `stateInFileB` are the same:
// assert(stateInFileA === stateInFileB); // this is true!

NOTE: This is "lazy" implementation of the singleton: The instance is not created until you call queryState.instance(). After initial call the return value is always the same.

Defaults in singleton scenario

Each of your module may desire to pass its own defaults. You can do it by passing optional defaults object:

// fileA.js
var stateInFileA = queryState.instance({name: 'John'});
// The query string now has `name=John` part.

// fileB.js
var stateInFileB = queryState.instance({age: 42});
// Now query string has both parts: `name=John&age=42`

// fileC.js
// Note: singleton instance never overwrites query string values. So if someone
// sets argument that already exists, the library will ignore it:
var stateInfileC = queryState.instance({age: 100, height: 180})

// The query string still has age 42, not 100:
// name=John&age=42&height=180

search instead of hash

By default query-state saves state in the hash part of the url. But what if we want to store state in the search part instead?

Instead of we want

Pass an optional argument to tell query-state use the search part:

var qs = queryState({
  answer: 42
}, {
  useSearch: true

clean up

Normally your app state will live as long as your application. However if you do need to clean up resources (e.g. unloading your app) you can call qs.dispose()

var qs = queryState();

// use it...

// and clean up when you need it:



You can’t perform that action at this time.