Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonlabelle/cookie-js
A tiny (1.24 KB gzipped), stand-alone JavaScript utility for managing cookies in the browser.
https://github.com/jonlabelle/cookie-js
cookie javascript javascript-utility vanilla-javascript
Last synced: 3 months ago
JSON representation
A tiny (1.24 KB gzipped), stand-alone JavaScript utility for managing cookies in the browser.
- Host: GitHub
- URL: https://github.com/jonlabelle/cookie-js
- Owner: jonlabelle
- License: mit
- Created: 2012-08-15T23:15:45.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2020-08-18T12:10:08.000Z (over 4 years ago)
- Last Synced: 2023-03-27T12:14:48.776Z (almost 2 years ago)
- Topics: cookie, javascript, javascript-utility, vanilla-javascript
- Language: JavaScript
- Homepage:
- Size: 113 KB
- Stars: 14
- Watchers: 2
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Cookie.js
A tiny (1.24 KB gzipped), stand-alone JavaScript utility for managing cookies in the browser.
## Usage
Add [Cookie.min.js](https://raw.githubusercontent.com/jonlabelle/cookie-js/master/Cookie.min.js) to your HTML document.
```html
```
## API
### Cookie.set()
**Create a cookie with no options specified**:
```javascript
Cookie.set('name', 'jon');
```
> **NOTE:** If the `option.expires` value is not set, the cookie `Expires / Max-Age` is set to *Session*.
**Create a cookie with an expiration date:**
```javascript
Cookie.set('name', 'jon', {
expires: new Date('March 18, 2040')
});
```
**Create a cookie that expires in 3 days:**
```javascript
Cookie.set('name', 'jon', {
expires: 3
});
```
**Create a cookie that can only be accessed by a specific** `path` **and** `domain`**:**
```javascript
Cookie.set('name', 'jon', {
path: '/', // all pages
domain: 'jonlabelle.com' // any subdomain of jonlabelle.com (including www)
});
```
**Create a secure cookie:**
```javascript
Cookie.set('name', 'jon', {
secure: true
});
```
> **NOTE:** Setting the `secure` option to `true` ensures the cookie will not be sent over non-https connections.
**Create a cookie and set the** [SameSite](https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite) **attribute:**
```javascript
Cookie.set('name', 'jon', {
sameSite: 'Strict'
});
```
The `SameSite` attribute accepts three values:
| Value | Description |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Lax` (*default*) | Cookies can sent in top-level navigations and will be sent along with GET request initiated by third party website. This is the default value in modern browsers. |
| `Strict` | Cookies will only be sent in a first-party context and not be sent along with requests initiated by third party websites. |
| `None` | Cookies will be sent in all contexts, i.e sending cross-origin is allowed. |
> **IMPORTANT:** If `SameSite` is not specified in cookie options, the default value will be set to `Lax` for a reasonably robust defense against some classes of cross-site request forgery. Learn more at [SameSite cookies explained](https://web.dev/samesite-cookies-explained).
### Cookie.get()
**Get a cookie accessible by the current page:**
```javascript
Cookie.get('name');
```
> **NOTE:** Returns `null` if the cookie does NOT exist.
### Cookie.exists()
**Check if a cookie exists:**
```javascript
if (Cookie.exists('name')) {
// do cool stuff here
}
```
> **NOTE:** Returns `bool`, `true` if the cookie exists, and `false` if it does not.
### Cookie Value Types
**Retrieve a cookie and convert the value to** `Number`**:**
```javascript
Cookie.set('age', 34);
var val = Cookie.get('age', Number);
if (typeof val === 'number') {
console.log(val); // 34
}
```
Other native functions that convert values are `Boolean` and `Date`, or you can define your own conversion `Function`.
For example, to create a number from a hexadecimal code:
```javascript
var value = Cookie.get('code', function (stringValue) {
return parseInt(stringValue, 16);
});
```
### Cookie.remove()
**Delete a cookie:**
```javascript
Cookie.remove('name');
```
**Delete a cookie specifying the** `domain`**:**
```javascript
Cookie.remove('info', {
domain: 'jonlabelle.com'
});
```
### Cookie.setSub()
Sub-cookies allow multiple values to be stored in a single cookie. A sub-cookie looks similar to a URL and takes the following form:
```text
cookiename=name1=value1&name2=value2&name3=value3
```
**Create a sub-cookie named** `person`**:**
```javascript
Cookie.setSub('person', 'name', 'jon');
Cookie.setSub('person', 'email', '[email protected]');
Cookie.setSub('person', 'today', (new Date()).toString());
```
**Create a sub-cookie with options:**
```javascript
Cookie.setSub('person', 'age', 75, { domain: 'jonlabelle.com', secure: true });
```
**Create a sub-cookie from an** `Object`**:**
```javascript
var obj = {
name: 'jon',
email: 'labelle'
};
Cookie.setSubs('person', obj);
```
> **NOTE:** Calls to `Cookie.setSubs()` will completely overwrite the cookie.
### Cookie.getSub()
**Get a sub-cookie:**
```javascript
Cookie.getSub('person', 'name');
```
**Get a sub-cookie and convert the value to a** `Number`**:**
```javascript
Cookie.getSub('person', 'age', Number);
```
### Cookie.getSubs()
**Get a sub-cookie as a hash** `Object`**:**
```javascript
var obj = Cookie.getSubs('person');
if (typeof obj === 'object') {
console.log(obj); // => Object { name: 'jon', email: '...'}
}
```
### Cookie.removeSub()
**Remove a sub-cookie:**
```javascript
Cookie.removeSub('person', 'name');
```
### Cookie.enabled()
**Check if cookies are enabled by the browser:**
```javascript
Cookie.enabled();
```
> **NOTE:** Returns `bool`, `true` if cookies are enabled, and `false` if they are not.
### Cookie.clear()
**Clear all cookies from the browser:**
```javascript
Cookie.clear();
```
## Author
[Jon LaBelle](mailto:[email protected])
## License
[MIT License](LICENSE.txt)