As cookies are just specially formatted strings it is sometimes difficult to manage them. This library aims to abstract the access to document.cookie by defining an object (docCookies) that is partially consistent with a Storage object. It also offers full Unicode support.

docCookies.setItem(name, value[, end[, path[, domain[, secure]]]])

Create/overwrite a cookie.

name

The name of the cookie to create/overwrite (string).

value

The value of the cookie (string).

end (optional)

The max-age in seconds (e.g. 31536e3 for a year, Infinity for a never-expire cookie), or the expires date in GMTString format or as Date object; if not, the specified the cookie will expire at the end of the session (number – finite or Infinity – string, Date object or null).

Note: Despite officially defined in RFC 6265, the use of max-age is not compatible with any version of Internet Explorer, Edge and some mobile browsers. Therefore passing a number to the end parameter might not work as expected. A possible solution might be to convert the the relative time to an absolute time. For instance, the following code:

docCookies.setItem("mycookie", "Hello world!", 150);

can be rewritten using an absolute date, as in the following example:

function maxAgeToGMT (nMaxAge) {
  return nMaxAge === Infinity ? "Fri, 31 Dec 9999 23:59:59 GMT" : (new Date(nMaxAge * 1e3 + Date.now())).toUTCString();
}

docCookies.setItem("mycookie", "Hello world!", maxAgeToGMT(150));

In the code above the function maxAgeToGMT() is used to create a GMTString from a relative time (i.e., from an "age").

path (optional)

The path from where the cookie will be readable. E.g., "/", "/mydir"; if not specified, defaults to the current path of the current document location (string or null). The path must be absolute (see RFC 2965). For more information on how to use relative paths in this argument, see this paragraph.

domain (optional)

The domain from where the cookie will be readable. E.g., "example.com", ".example.com" (includes all subdomains) or "subdomain.example.com"; if not specified, defaults to the host portion of the current document location (string or null).

secure (optional)

The cookie will be transmitted only over secure protocol as https (boolean or null).

docCookies.getItem(name)

Read a cookie. If the cookie doesn't exist a null value will be returned.

name

The name of the cookie to read (string).

docCookies.removeItem(name[, path[, domain]])

Delete a cookie.

name

The name of the cookie to remove (string).

path (optional)

E.g., "/", "/mydir"; if not specified, defaults to the current path of the current document location (string or null). The path must be absolute (see RFC 2965). For more information on how to use relative paths in this argument, see this paragraph.

domain (optional)

E.g., "example.com", or "subdomain.example.com"; if not specified, defaults to the host portion of the current document location (string or null), but not including subdomains. Contrary to earlier specifications, leading dots in domain names are ignored. If a domain is specified, subdomains are always included.

Note: To delete cookies that span over subdomains, you need to explicitate the domain attribute in removeItem() as well as setItem().

docCookies.hasItem(name)

Check whether a cookie exists in the current position.

name

The name of the cookie to test (string).

docCookies.keys()

Returns an array of all cookies readable from this location.

docCookies.clear([path[, domain]])

Clears all cookies readable from this location.

path (optional)

E.g., "/", "/mydir"; if not specified, defaults to the current path of the current document location (string or null). The path must be absolute (see RFC 2965). For more information on how to use relative paths in this argument, see this paragraph.

domain (optional)

E.g., "example.com", or "subdomain.example.com"; if not specified, defaults to the host portion of the current document location (string or null), but not including subdomains. Contrary to earlier specifications, leading dots in domain names are ignored. If a domain is specified, subdomains are always included.

docCookies.setItem("test0", "Hello world!");
docCookies.setItem("test1", "Unicode test: \u00E0\u00E8\u00EC\u00F2\u00F9", Infinity);
docCookies.setItem("test2", "Hello world!", new Date(2020, 5, 12));
docCookies.setItem("test3", "Hello world!", new Date(2027, 2, 3), "/blog");
docCookies.setItem("test4", "Hello world!", "Wed, 19 Feb 2127 01:04:55 GMT");
docCookies.setItem("test5", "Hello world!", "Fri, 20 Aug 88354 14:07:15 GMT", "/home");
docCookies.setItem("test6", "Hello world!", 150);
docCookies.setItem("test7", "Hello world!", 245, "/content");
docCookies.setItem("test8", "Hello world!", null, null, "example.com");
docCookies.setItem("test9", "Hello world!", null, null, null, true);
docCookies.setItem("test1;=", "Safe character test;=", Infinity);

alert(docCookies.keys().join("\n"));
alert(docCookies.getItem("test1"));
alert(docCookies.getItem("test5"));
docCookies.removeItem("test1");
docCookies.removeItem("test5", "/home");
alert(docCookies.getItem("test1"));
alert(docCookies.getItem("test5"));
alert(docCookies.getItem("unexistingCookie"));
alert(docCookies.getItem());
alert(docCookies.getItem("test1;="));

If you plan to modify the source code or make PR to this project, please, keep in mind the following information.

We use Grunt plugins to minify the JS and build the source map file. Grunt and Grunt plugins are installed and managed via npm, the Node.js package manager. Use the following instructions to install them:

• Download and install Node.js with npm
• Install Grunt by command npm install in the root of the project.

Now you can run the default task in Grunt that will minify the JS and generate the source map file. You can run it either with your IDE or by typing grunt command in the command line in the root of the project.