Using cookies in JavaScript

Cookies are small items of data, each consisting of a name and a value, stored on behalf of a website by visitors’ web browsers. In JavaScript, cookies can be accessed through the document.cookie property, but the interface provided by this property is very primitive. Cookies.js is a JavaScript object that allows cookies to be created, retrieved, and deleted through a simple and intuitive interface.

Download Cookies.js

Download one of the files below and upload it to your web server.

Link to the file using a script element in the head of your page:

1

<script type="text/javascript" src="Cookies.js"></script>

Creating cookies

Cookies can be created using the set function of the Cookie object, which takes the cookie name and value as parameters:

1
2

// create a cookie
Cookie.create('theme', 'green');

A cookie set in this way will be deleted when the visitor closes their web browser, will only be accessible within the current directory on the current domain name, and will be sent over both encrypted and unencrypted connections. These features can be controlled through an additional four parameters that may be passed to the set function. Each of these parameters is optional; to set a later parameter without setting an earlier parameter pass null as the value of the earlier parameter, as shown in some of the examples below.

The third parameter allows the cookie can be given an expiry date. Cookies with an expiry date will persist between browsing sessions, and only be deleted when the expiry date is reached or the visitor instructs the browser to do so. The value of the parameter can be either a date on which the cookie will expire or a number of days after which the cookie should expiry:

1
2
3
4
5

// set a cookie that expires after thirty days
Cookie.create('theme', 'green', 30);

// set a cookie that expires on 1st January 2030
Cookie.create('name', 'Stephen Morley', new Date(2030, 1, 1));

Every cookie is accessible only within a particular path, which defaults to the current directory — for example, a cookie set on a page at http://example.com/news/ would by default be accessible from http://example.com/news/archives/ but not from the home page of the site. The fourth parameter allows an alternative path to be specified:

1
2
3
4
5

// set a cookie that is accessible anywhere on the site
Cookie.create('theme', 'green', null, '/');

// set a cookie that is accessible only within the news directory
Cookie.create('country', 'uk', null, '/news/');

Every cookie is accessible only on a particular domain, which defaults to the current domain, and its subdomains — for example, a cookie set on news.example.com would by default be accessible from archives.news.example.com but not from the main domain example.com. The fifth parameter allows an alternative domain to be specified:

1
2

// set a cookie that is accessible on all subdomains of example.com
Cookie.create('theme', 'green', null, null, '.example.com');

Finally, the sixth parameter can be set to true to instruct the browser to send the cookie only over encrypted connections:

1
2

// set a cookie that is sent only over encrypted connections
Cookie.create('theme', 'green', null, null, null, true);

Retrieving cookies

The value of a cookie can be retrieved using the get function of the Cookie object, which takes the cookie name as a parameter:

1
2

// retrieve the value of the theme cookie
var theme =  Cookie.get('theme');

If there is no cookie with the specified name, the value ‘undefined’ is returned. There may be more than one cookie with the same name, if they were set for different paths or subdomains. In this case the get function returns the most specific cookie (that is, the one set for the longest path). Passing true as a second parameter to the get function will cause it to return an array containing the values of all cookies with the specified name, in order of specificity:

1
2

// retrieve the values of any theme cookies
var themes =  Cookie.get('theme', true);

Deleting cookies

A cookie can be deleted using the clear function of the Cookie object, which takes the cookie name as a parameter:

1
2

// delete the theme cookie
Cookie.clear('theme');

If the cookie was set for a path or domain other than the current path and domain, these must be passed as parameters to the clear function:

1
2

// delete the site-wide theme cookie
Cookie.clear('theme', '/', '.example.com');