cookie-component

Client-Side Cookie Manipulation API

Cookies.js

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.

API Reference

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, [, 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 , 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 . 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 '/'

Change Log

  • 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 value with Cookies.set now expires the cookie, mirroring the Cookies.expire alias syntax.
  • Simplified how the document.cookie string is parsed.
  • Fixed a bug where setting a cookie's secure value tofalse caused the Cookies.defaults.secure value to be used instead.
  • Added aliases for Cookies.set and Cookies.expire.
  • Set Cookies.defaults.path to '/'.
  • Replaced escape and unescape function calls with encodeURIComponent and decodeURIComponent, because the former are deprecated.
  • Cookie keys are now URI encoded in addition to cookie values.
  • Cross browser fixes.
  • Initial commit.