Cookies.js is a small client-side javascript library that makes managing cookies easy.
- Caches cookie values, making sequential reads faster.
- Supports AMD / CommonJS loaders.
- Cross browser.
- Lightweight (less than 1 KB, minified and gzipped).
The following browsers have passed all of the Cookies.js unit tests:
- Chrome
- Firefox 3+
- Safari 4+
- Opera 10+
- Internet Explorer 6+
Cookies.js URI encodes cookie keys and values, and expects cookie keys to be URI encoded when accessing a cookie. Keep this in mind when working with cookies on the server side.
Do not use HttpUtility.UrlEncode and
HttpUtility.UrlDecode on cookie keys or values. HttpUtility.UrlEncode will
improperly escape space characters to '+' and lower case every escape sequence. HttpUtility.UrlDecode will improperly unescape
every '+' to a space character. Instead, use
System.Uri.EscapeDataString and
System.Uri.UnescapeDataString.
Alias: Cookies(key, value [, options])
Sets a cookie in the document. If the cookie does not already exist, it will be created.
key: A string value of the cookie key to set
value: A string value of the cookie value to set
options: An object containing additional parameters about the cookie (discussed below)
The Cookies object is returned to support chaining.
path: A string value of the path of the cookie
domain: A string value of the domain of the cookie
expires: A number (of seconds), a date parsable string, or a Date object of when the cookie will expire
secure: A boolean value of whether or not the cookie should only be available over SSL
If any property is left undefined, the browser's default value will be used instead. A default value
for any property may be set in the Cookies.defaults object.
Why use 'expires' instead of 'max-age' (or why not both)?
Internet Explorer 6 - 8 do not support 'max-age', so Cookies.js always uses 'expires' internally.
However, Cookies.js simplifies things by allowing the options.expires property to be used in the
same way as 'max-age' (by setting options.expires to the number of seconds the cookie should exist for).
// Setting a cookie value
Cookies.set('key', 'value');
// Chaining sets together
Cookies.set('key', 'value').set('hello', 'world');
// Setting cookies with additional options
Cookies.set('key', 'value', { domain: 'www.example.com', secure: true });
// Setting cookies with expiration values
Cookies.set('key', 'value', { expires: 600 }); // Expires in 10 minutes
Cookies.set('key', 'value', { expires: '01-01-2012' });
Cookies.set('key', 'value', { expires: new Date(2012, 0, 1) });
// Using the alias
Cookies('key', 'value', { secure: true });
Alias: Cookies(key)
Retrieves the cookie value of the most locally scoped cookie with the specified key.
key: A string value of a cookie key
The string value of the cookie.
// First set a cookie
Cookies.set('key', 'value');
// Get the cookie value
Cookies.get('key'); // "value"
// Using the alias
Cookies('key'); // "value"
Alias: Cookies(key, undefined [, options])
Expires a cookie, removing it from the document.
key: A string value of the cookie key to expire
options: An object containing additional parameters about the cookie (discussed below)
The Cookies object is returned to support chaining.
path: A string value of the path of the cookie
domain: A string value of the domain of the cookie
If any property is left undefined, the browser's default value will be used instead. A default value
for any property may be set in the Cookies.defaults object.
// First set a cookie and get its value
Cookies.set('key', 'value').get('key'); // "value"
// Expire the cookie and try to get its value
Cookies.expire('key').get('key'); // undefined
// Using the alias instead
Cookies('key', undefined);
A boolean value of whether or not the browser has cookies enabled.
if (Cookies.enabled) {
Cookies.set('key', 'value');
}
An object representing default options to be used when setting and expiring cookie values.
Cookies.defaults supports the following properties:
path: A string value of the path of the cookie
domain: A string value of the domain of the cookie
expires: A number (of seconds), a date parsable string, or a Date object of when the cookie will expire
secure: A boolean value of whether or not the cookie should only be available over SSL
By default, only Cookies.defaults.path is set to '/', all other properties are undefined.
If any property is left undefined, the browser's default value will be used instead.
Cookies.defaults = {
path: '/',
secure: true
};
Cookies.set('key', 'value'); // Will be secure and have a path of '/'
Cookies.expire('key'); // Will expire the cookie with a path of '/'
- Cookie values are no longer automatically JSON encoded/decoded. This featured was deemed out of the scope of the library. This change also removes the dependency on a JSON shim for older browsers.
- Changed cookie value encoding to only encode the special characters defined in RFC6265
- Added
'use strict';directive. - Removed some extraneous code.
- Added CommonJS module support.
- Setting an
undefinedvalue withCookies.setnow expires the cookie, mirroring theCookies.expirealias syntax. - Simplified how the
document.cookiestring is parsed.
- Fixed a bug where setting a cookie's
securevalue tofalsecaused theCookies.defaults.securevalue to be used instead.
- Added aliases for
Cookies.setandCookies.expire.
- Set
Cookies.defaults.pathto'/'. - Replaced
escapeandunescapefunction calls withencodeURIComponentanddecodeURIComponent, because the former are deprecated. - Cookie keys are now URI encoded in addition to cookie values.
- Cross browser fixes.
- Initial commit.