[Chapter 21] Reference: Document.cookie
Author: David Flanagan
Date: Fri Aug 29 11:15:02 1997

#

| Chapter 21 JavaScript Reference |

# Document.cookie Property

## Name

Document.cookie Property---the cookie(s) of the document

## Availability

Navigator 2.0, partial support in Internet Explorer 3.0

## Synopsis

    document.cookie

## Description

`cookie` is a string property that allows you to read, create, modify, and delete the cookie or cookies that apply to the current document. A cookie is a small amount of named data stored by the web browser. It serves to give web browsers a "memory", so that they can use data input on one page in another page, or so they can recall user preferences across web browsing sessions. Cookie data is automatically transmitted between web browser and web server when appropriate, so that CGI scripts on the server end can read and write cookie values. Client-side JavaScript code can also read and write cookies with this property. For a more complete discussion of cookies, see Netscape's cookie specification at http://home.netscape.com/newsref/std/cookie_spec.html.

Internet Explorer 3.0 supports the `cookie` property only when the document was retrieved via the HTTP protocol. Documents retrieved from the local file system, or via other protocols such as FTP and Gopher cannot utilize cookies. This limitation will be removed in a future version of Internet Explorer.

The `Document.cookie` property does not behave like a normal read/write property. You may both read and write the value of of `Document.cookie`, but the value you read from this property will, in general, not be the same as the value you write. The following subsections explain how to read and write cookie values.

### Reading Cookie Values

When you use the `cookie` property in a JavaScript expression, the value it returns is a string containing all the cookies that apply to the current document. The string is a list of `name``=``value` pairs separated by semicolons, where `name` is the name of a cookie, and `value` is its string value. You can use the `String.indexOf()` and `String.substring()` methods to determine the value of the named cookie you are interested in.

Once you have obtained the value of a cookie in this way, you must interpret that value based on whatever format or encoding was used by the creator of that cookie. For example, the cookie might store multiple pieces of information in colon-separated fields. In this case, you would have to use appropriate string methods to extract the various fields of information.

The value of a cookie must not contain any semicolons, commas, or whitespace. Because these are commonly used characters, it is common to use the JavaScript `escape()` function to encode cookie values before storing them, and the `unescape()` function to decode the values after retrieving them.

Note that the `Document.cookie` field provides no way to obtain the domain, path, expiration, or secure fields associated with a cookie.

### Storing Cookies

To associate a temporary cookie value with the current document, simply set `document``.cookie` to a string of the form `name``=``value`. The next time you read `document``.cookie`, the `name` and `value` pair will be included in the list of cookies for the document. As noted above, the cookie value may not include semicolons, commas or whitespace. For this reason, you may want to use the JavaScript `escape()` function to encode the value before storing it in the cookie.

A cookie written as described above will last for the current web browsing session, but will be lost when the user exits the browser. To create a cookie that can last across browser sessions, include an expiration date. You can do this by setting `document``.cookie` to a string of the form:

    name=value; expires=date

`date` should be a date specification in the format written by `Date.toGMTString()`.

Similarly, you can set the path, domain, and secure fields of a cookie by appending strings of the following form to the cookie value before that value is written to the `document``.cookie` property. (See http://home.netscape.com/newsref/std/ cookie_spec.html for more information about the meaning of the path, domain, and secure fields of a cookie.)

    ; path=path
    ; domain=domain
    ; secure

To change the value of a cookie, set its value again, using the same name (and the same path and domain, if any) and the new value.

To delete a cookie, set it again using the same name, path and domain, an arbitrary value, and an expiration date that has already passed. Note that the browser is not required to immediately delete expired cookies. In practice, with Netscape Navigator, cookie deletion seems to work more effectively if the expiration date is in the relatively distant (several hours or more) past.

## Usage

Cookies are intended for infrequent storage of small amounts of data. They are not intended as a general-purpose communication or programming mechanism; use them in moderation. Note that web browsers are not required to retain the value of more than 20 cookies per web server (for the entire server, not just for your site on the server), nor to retain a cookie `name`/`value` pair more than 4 kilobytes in length.

## Bugs

In Internet Explorer 3.0, cookies and the `cookie` property only work for documents retrieved via the HTTP protocol.

## See Also

Chapter 15, Saving State with Cookies

Document.close() |  | Document.domain