Forked from https://github.com/madmurphy/cookies.js.
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[, samesite="lax"]]]]])
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
) -
samesite
(optional) -
The default value is
"lax"
.Prevents the browser from sending the cookie along with cross-site requests (see
samesite
flag); possible values are:"no_restriction"
(case insensitive) orfalse
or0
: don't express any preference (in most cases this means that the cookie will allow cross-site requests, but this is likely going to change in the future)"none"
(case insensitive) or a negative number: the cookie will allow cross-site requests (experimental)"lax"
(case insensitive) or1
ortrue
orundefined
ornull
: cookies will only be sent for TOP LEVEL navigation GET requests – this is sufficient for user tracking, but it will prevent many CSRF attacks"strict"
(case insensitive) or any other value not matching the previous cases: thestrict
flag will prevent the cookie from being sent by the browser to the target site in all cross-site browsing context, even when following a regular link.
docCookies.getItem(name)
Read a cookie; if the cookie doesn't exist or is not reachable from the current location a null
value will be returned
docCookies.removeItem(name[, path[, domain[, secure[, samesite="lax"]]]])
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 -
secure
(optional) -
The cookie will be removed only over
secure
protocol as https (boolean
ornull
) -
samesite
(optional) -
The default value is
"lax"
.Prevents the browser from sending the cookie along with cross-site requests (see
samesite
flag); possible values are:"no_restriction"
(case insensitive) orfalse
or0
: don't express any preference (in most cases this means that the cookie will allow cross-site requests, but this is likely going to change in the future)"none"
(case insensitive) or a negative number: the cookie will allow cross-site requests (experimental)"lax"
(case insensitive) or1
ortrue
orundefined
ornull
: cookies will only be sent for TOP LEVEL navigation GET requests – this is sufficient for user tracking, but it will prevent many CSRF attacks"strict"
(case insensitive) or any other value not matching the previous cases: thestrict
flag will prevent the cookie from being sent by the browser to the target site in all cross-site browsing context, even when following a regular link.
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 and is reachable from the current location
docCookies.keys()
Return an array of all cookies readable from the current location
docCookies.clear([path[, domain[, secure[, samesite="lax"]]]])
Clear all cookies readable from the current location
-
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 -
secure
(optional) -
The cookies will be removed only over
secure
protocol as https (boolean
ornull
) -
samesite
(optional) -
The default value is
"lax"
.Prevents the browser from sending the cookie along with cross-site requests (see
samesite
flag); possible values are:"no_restriction"
(case insensitive) orfalse
or0
: don't express any preference (in most cases this means that the cookie will allow cross-site requests, but this is likely going to change in the future)"none"
(case insensitive) or a negative number: the cookie will allow cross-site requests (experimental)"lax"
(case insensitive) or1
ortrue
orundefined
ornull
: cookies will only be sent for TOP LEVEL navigation GET requests – this is sufficient for user tracking, but it will prevent many CSRF attacks"strict"
(case insensitive) or any other value not matching the previous cases: thestrict
flag will prevent the cookie from being sent by the browser to the target site in all cross-site browsing context, even when following a regular link.
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;="));