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
-
value
-
end
(optional) -
The
max-age
in seconds (e.g.31536e3
for a year,Infinity
for a never-expire cookie), or theexpires
date inGMTString
format or asDate
object; if not, the specified the cookie will expire at the end of the session (number
โ finite orInfinity
โstring
,Date
object ornull
).
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 theend
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 aGMTString
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
ornull
). 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
ornull
). -
secure
(optional) -
The cookie will be transmitted only over
secure
protocol as https (boolean
ornull
).
docCookies.getItem(name)
Read a cookie. If the cookie doesn't exist a null
value will be returned.
docCookies.removeItem(name[, path[, domain]])
Delete a cookie.
-
name
-
path
(optional) -
E.g.,
"/"
,"/mydir"
; if not specified, defaults to the current path of the current document location (string
ornull
). 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
ornull
), 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.
docCookies.keys()
Returns an array of all readable cookies from this location.
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;="));