# cookies-js

> Client-Side Cookie Manipulation API

Latest version **1.2.3** (published 2016-11-06) · Public Domain license · 0 weekly downloads

## Install

```sh
npm install cookies-js
pnpm add cookies-js
yarn add cookies-js
bun add cookies-js
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.3 |
| Published | 2016-11-06 |
| First published | 2013-05-03 |
| Weekly downloads | 0 |
| License | Public Domain |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1762 |
| Author | Scott Hamper |
| Maintainers | scotthamper |
| Keywords | cookies, client, browser |

## Links

- npm: https://www.npmjs.com/package/cookies-js
- Repository: https://github.com/ScottHamper/Cookies
- Homepage: http://github.com/ScottHamper/Cookies
- Issues: https://github.com/ScottHamper/Cookies/issues
- npm.io page: https://npm.io/package/cookies-js

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 1.2.3 (latest) — 2016-11-06
- 1.2.2 — 2015-09-10
- 1.2.1 — 2015-02-16
- 1.2.0 — 2015-02-10
- 1.1.0 — 2014-11-07
- 1.0.1 — 2014-11-07
- 1.0.0 — 2014-10-26
- 0.4.0 — 2014-04-29
- 0.3.1 — 2013-05-03

## README

# Cookies.js

Cookies.js is a small client-side javascript library that makes managing cookies easy.

[Features](#features)  
[Browser Compatibility](#browser-compatibility)  
[Getting the Library](#getting-the-library)  
[Use in CommonJS/Node Environments Without `window`](#use-in-commonjsnode-environments-without-window)  
[A Note About Encoding](#a-note-about-encoding)  
[API Reference](#api-reference)

## Features
- [RFC6265](http://www.rfc-editor.org/rfc/rfc6265.txt) compliant
- Cross browser
- Lightweight
- No dependencies
- Public domain
- Supports AMD / CommonJS loaders

## Browser Compatibility
The following browsers have passed all of the automated Cookies.js tests:
- Chrome
- Firefox 3+
- Safari 4+
- Opera 10+
- Internet Explorer 6+

## Getting the Library
#### Direct downloads
- [v1.2.3 Minified](https://raw.github.com/ScottHamper/Cookies/1.2.3/dist/cookies.min.js) (~1 KB gzipped)
- [v1.2.3 Unminified](https://raw.github.com/ScottHamper/Cookies/1.2.3/dist/cookies.js) (~1.7 KB gzipped)

#### Node Package Manager
`npm install cookies-js`

#### Bower
`bower install cookies-js`

## Use in CommonJS/Node Environments Without `window`
In environments where there is no native `window` object, Cookies.js will export a factory method
that accepts a `window` instance. For example, using [jsdom](https://github.com/tmpvar/jsdom), you
might do something like:

```javascript
var jsdom = require('jsdom');
var window = jsdom.jsdom().parentWindow;
var Cookies = require('cookies-js')(window);

// Use Cookies as you normally would
```

## A Note About Encoding
[RFC6265](http://www.rfc-editor.org/rfc/rfc6265.txt) defines a strict set of allowed characters for
cookie keys and values. In order to effectively allow any character to be used in a key or value,
Cookies.js will URI encode disallowed characters in their UTF-8 representation. As such, Cookies.js
also expects cookie keys and values to already be URI encoded in a UTF-8 representation when it
accesses cookies. Keep this in mind when working with cookies on the server side.

#### .NET Users
Do not use [HttpUtility.UrlEncode](http://msdn.microsoft.com/en-us/library/4fkewx0t.aspx) and
[HttpUtility.UrlDecode](http://msdn.microsoft.com/en-us/library/adwtk1fy.aspx) on cookie keys or
values. `HttpUtility.UrlEncode` will improperly escape space characters to `'+'` and lower case every
escape sequence. `HttpUtility.UrlDecode` will improperly unescape every `'+'` to a space character.
Instead, use
[System.Uri.EscapeDataString](http://msdn.microsoft.com/en-us/library/system.uri.escapedatastring.aspx)
and [System.Uri.UnescapeDataString](http://msdn.microsoft.com/en-us/library/system.uri.unescapedatastring.aspx).


## API Reference

**Methods**  
[Cookies.set(key, value [, options])](#cookiessetkey-value--options)  
[Cookies.get(key)](#cookiesgetkey)  
[Cookies.expire(key [, options])](#cookiesexpirekey--options)

**Properties**  
[Cookies.enabled](#cookiesenabled)  
[Cookies.defaults](#cookiesdefaults)

### Methods

#### Cookies.set(key, value [, options])
*Alias: Cookies(key, value [, options])*

Sets a cookie in the document. If the cookie does not already exist, it will be created. Returns the `Cookies` object.

| Option    | Description                                                                                      | Default     |
| --------: | ------------------------------------------------------------------------------------------------ | ----------- |
|    *path* | A string value of the path of the cookie                                                         | `"/"`       |
|  *domain* | A string value of the domain of the cookie                                                       | `undefined` |
| *expires* | A number (of seconds), a date parsable string, or a `Date` object of when the cookie will expire | `undefined` |
|  *secure* | A boolean value of whether or not the cookie should only be available over SSL                   | `false`     |

A default value for any option may be set in the `Cookies.defaults` object.

**Example Usage**
```javascript
// Setting a cookie value
Cookies.set('key', 'value');

// Chaining sets together
Cookies.set('key', 'value').set('hello', 'world');

// Setting cookies with additional options
Cookies.set('key', 'value', { domain: 'www.example.com', secure: true });

// Setting cookies with expiration values
Cookies.set('key', 'value', { expires: 600 }); // Expires in 10 minutes
Cookies.set('key', 'value', { expires: '01/01/2012' });
Cookies.set('key', 'value', { expires: new Date(2012, 0, 1) });
Cookies.set('key', 'value', { expires: Infinity });

// Using the alias
Cookies('key', 'value', { secure: true });
```

#### Cookies.get(key)
*Alias: Cookies(key)*

Returns the value of the most locally scoped cookie with the specified key.

**Example Usage**
```javascript
// First set a cookie
Cookies.set('key', 'value');

// Get the cookie value
Cookies.get('key'); // "value"

// Using the alias
Cookies('key'); // "value"
```
    
#### Cookies.expire(key [, options])
*Alias: Cookies(key, `undefined` [, options])*

Expires a cookie, removing it from the document. Returns the `Cookies` object.

| Option    | Description                                                                                      | Default     |
| --------: | ------------------------------------------------------------------------------------------------ | ----------- |
|    *path* | A string value of the path of the cookie                                                         | `"/"`       |
|  *domain* | A string value of the domain of the cookie                                                       | `undefined` |

A default value for any option may be set in the `Cookies.defaults` object.

**Example Usage**
```javascript
// First set a cookie and get its value
Cookies.set('key', 'value').get('key'); // "value"

// Expire the cookie and try to get its value
Cookies.expire('key').get('key'); // undefined

// Using the alias
Cookies('key', undefined);
```
    

### Properties

#### Cookies.enabled
A boolean value of whether or not the browser has cookies enabled.

**Example Usage**
```javascript
if (Cookies.enabled) {
    Cookies.set('key', 'value');
}
```

#### Cookies.defaults
An object representing default options to be used when setting and expiring cookie values.

| Option    | Description                                                                                      | Default     |
| --------: | ------------------------------------------------------------------------------------------------ | ----------- |
|    *path* | A string value of the path of the cookie                                                         | `"/"`       |
|  *domain* | A string value of the domain of the cookie                                                       | `undefined` |
| *expires* | A number (of seconds), a date parsable string, or a `Date` object of when the cookie will expire | `undefined` |
|  *secure* | A boolean value of whether or not the cookie should only be available over SSL                   | `false`     |

**Example Usage**
```javascript
Cookies.defaults = {
    path: '/',
    secure: true
};

Cookies.set('key', 'value'); // Will be secure and have a path of '/'
Cookies.expire('key'); // Will expire the cookie with a path of '/'
```

---
_Source: https://npm.io/package/cookies-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._