cookie.js is a tiny JavaScript library that simplifies cookies. It is capable of setting, getting and removing cookies, accepts a variety of parameters, and supports chaining. It doesn't have any dependencies and minified+gzipped it's only 0.9 KB small.

Working with cookies in JavaScript sucks. document.cookie is definitely one of the ugly parts of JavaScript. This library aims to provide an easy and nevertheless powerful way to use cookies.

Download cookie.min.js and include it in your HTML document, this will add a global object called cookie:

<script src="cookie.min.js"></script>

Alternatively you can use a JavaScript package manager to add it to your project:

$ bower install cookie --save
$ jam install cookie
$ npm install cookie_js --save

cookie.js supports AMD and CommonJS. So if you want to include cookie.js dynamically, you can just require it with any AMD / CommonJS loader, for example RequireJS for AMD. Follow the instructions of your loader to include cookie.js.

After that you can call any of methods that are explained in the following.

You can use the cookie.set method to set cookies. The value will automatically be escaped for you.

cookie.set('key', 'value');

Note: Values will be casted to string, so setting a number will work. However, the value will be a string when getting the cookie.

You can also set several values at once:

cookie.set({
   key1: 'value1',
   key2: 'value2'
});

If you need more options, like setting the expiry date, you can add an object with options as the last parameter:

cookie.set('key', 'value', {
   expires: 7, // expires in one week
});

cookie.set({
   key1: 'value1',
   key2: 'value2'
}, {
   expires: 7
})

The following fields can be added to the mentioned object:

You can customize the default settings by manipulating cookie.defaults.

cookie.defaults.expires = 7;
cookie.defaults.secure = true;

Most people will prefer specifying the expiry date in days, but if you want to specify the expiry date in minutes, then you can configure cookie.expiresMultiplier:

cookie.expiresMultiplier = 60; // Seconds.
cookie.expiresMultiplier = 60 * 60; // Minutes.
cookie.expiresMultiplier = 60 * 60 * 24; // Hours.

This method allows you to retrieve your cookies, you can use it by simply passing the key of the cookie:

cookie.get('key');

Passing just one key like this will return a string, containing the value of the cookie. You can also pass an array of keys:

cookie.get(['key1', 'key2']);

This will always return an object. The keys of this object will be the keys you passed and the values are the corresponding values.

In case you want to add a default value you can use the second parameter. The default value will be returned if the cookie*(s)* could not be found:

cookie.get('key', 'default value');

This also works with several keys:

cookie.get(['key1', 'key2'], 'default value');

cookie() is a shortcut for cookie.get().

cookie.get('key');
// is the same as
cookie('key');

var cookies = cookie.all();

To get all of the currently saved cookies simply call cookie.all. In this case the variable cookies will return an object with all the current cookies.

This method allows you to remove cookies. It accepts an infinite number of keys or an array of keys.

cookie.remove('key');
cookie.remove('key1', 'key2');
cookie.remove(['key1', 'key2']);

Sometimes you may want to remove all cookies. Simply call cookie.empty() and every cookie will be removed.

This method allows you to test if the cookies are enabled. It returns true if you can work with cookies and false if you cannot. You might want to use a fallback if they are disabled:

if (cookie.enabled()) {
   // Do stuff with cookies
} else {
   // Display error message or use localStorage
}

This method works just like cookie.set and accepts the same arguments, but it only sets those cookies that don't have a value yet allowing you to specify default values.

cookie.set('a', '1');
cookie.setDefault({
   a: '2',
   b: '2'
});

cookie.get(['a', 'b']); // {a: "1", b: "2"}

The methods set, remove and empty return the cookie object and therefore enable chaining.

cookie.empty().set('key1', 'value1').set('key2', 'value2').remove('key1');

cookie.js sensibly encodes / decodes values and should work just fine with most server side frameworks. However sometimes there are weird server side encodings, for example PHP escapes spaces with + for historic reasons. This library can't handle all of those cases at the same time so if you notice you need a custom decoding function you can overwrite cookie.utils.decode.

// For example
cookie.utils.decode = function (value) {
   return decodeURIComponent(value).replace('+', ' ');
};

• Contribute
• Changelog