1# jquery.cookie [![Build Status](https://travis-ci.org/carhartl/jquery-cookie.png?branch=master)](https://travis-ci.org/carhartl/jquery-cookie)
2
3A simple, lightweight jQuery plugin for reading, writing and deleting cookies.
4
5## Installation
6
7Include script *after* the jQuery library (unless you are packaging scripts somehow else):
8
9    <script src="/path/to/jquery.cookie.js"></script>
10
11**Do not include the script directly from GitHub (http://raw.github.com/...).** The file is being served as text/plain and as such being blocked
12in Internet Explorer on Windows 7 for instance (because of the wrong MIME type). Bottom line: GitHub is not a CDN.
13
14The plugin can also be loaded as AMD module.
15
16## Usage
17
18Create session cookie:
19
20    $.cookie('the_cookie', 'the_value');
21
22Create expiring cookie, 7 days from then:
23
24    $.cookie('the_cookie', 'the_value', { expires: 7 });
25
26Create expiring cookie, valid across entire site:
27
28    $.cookie('the_cookie', 'the_value', { expires: 7, path: '/' });
29
30Read cookie:
31
32    $.cookie('the_cookie'); // => "the_value"
33    $.cookie('not_existing'); // => undefined
34
35Read all available cookies:
36
37    $.cookie(); // => { "the_cookie": "the_value", "...remaining": "cookies" }
38
39Delete cookie:
40
41    // Returns true when cookie was found, false when no cookie was found...
42    $.removeCookie('the_cookie');
43
44    // Same path as when the cookie was written...
45    $.removeCookie('the_cookie', { path: '/' });
46
47*Note: when deleting a cookie, you must pass the exact same path, domain and secure options that were used to set the cookie, unless you're relying on the default options that is.*
48
49## Configuration
50
51### raw
52
53By default the cookie value is encoded/decoded when writing/reading, using `encodeURIComponent`/`decodeURIComponent`. Bypass this by setting raw to true:
54
55    $.cookie.raw = true;
56
57### json
58
59Turn on automatic storage of JSON objects passed as the cookie value. Assumes `JSON.stringify` and `JSON.parse`:
60
61    $.cookie.json = true;
62
63## Cookie Options
64
65Cookie attributes can be set globally by setting properties of the `$.cookie.defaults` object or individually for each call to `$.cookie()` by passing a plain object to the options argument. Per-call options override the default options.
66
67### expires
68
69    expires: 365
70
71Define lifetime of the cookie. Value can be a `Number` which will be interpreted as days from time of creation or a `Date` object. If omitted, the cookie becomes a session cookie.
72
73### path
74
75    path: '/'
76
77Define the path where the cookie is valid. *By default the path of the cookie is the path of the page where the cookie was created (standard browser behavior).* If you want to make it available for instance across the entire domain use `path: '/'`. Default: path of page where the cookie was created.
78
79**Note regarding Internet Explorer:**
80
81> Due to an obscure bug in the underlying WinINET InternetGetCookie implementation, IE’s document.cookie will not return a cookie if it was set with a path attribute containing a filename.
82
83(From [Internet Explorer Cookie Internals (FAQ)](http://blogs.msdn.com/b/ieinternals/archive/2009/08/20/wininet-ie-cookie-internals-faq.aspx))
84
85This means one cannot set a path using `path: window.location.pathname` in case such pathname contains a filename like so: `/check.html` (or at least, such cookie cannot be read correctly).
86
87### domain
88
89    domain: 'example.com'
90
91Define the domain where the cookie is valid. Default: domain of page where the cookie was created.
92
93### secure
94
95    secure: true
96
97If true, the cookie transmission requires a secure protocol (https). Default: `false`.
98
99## Tests
100
101Requires Node. Startup server:
102
103    $ node test/server.js
104
105Open in browser:
106
107    $ open http://0.0.0.0:8124/test/index.html
108
109For quick *non cross-browser* testing use grunt, install grunt CLI and project dependencies as outlined in this guide: <http://gruntjs.com/getting-started>, then run:
110
111    $ grunt
112
113## Development
114
115- Source hosted at [GitHub](https://github.com/carhartl/jquery-cookie)
116- Report issues, questions, feature requests on [GitHub Issues](https://github.com/carhartl/jquery-cookie/issues)
117
118Pull requests are very welcome! Make sure your patches are well tested. Please create a topic branch for every separate change you make.
119
120## Authors
121
122[Klaus Hartl](https://github.com/carhartl)
123