es-cookie

A simple, lightweight module for handling cookies

• Includes TypeScript definitions
• Works with Webpack, Rollup, and Browserify module bundlers
• Fully compliant with RFC 6265
• No dependencies other than an Object.assign polyfill if using Internet Explorer (core-js is recommended)
• Originally based on js-cookie, but rewritten as a TypeScript module with a lean, type-safe API

Installation

npm install es-cookie --save

Usage

Import entire module:

import * as Cookies from 'es-cookie';

Cookies.set('name', 'value');
Cookies.get('name'); // => 'value'

Alternatively, just import the functions you need:

import {set as setCookie, get as getCookie} from 'es-cookie';

setCookie('name', 'value');
getCookie('name'); // => 'value'

Create a cookie that expires 7 days from now, valid across the entire site:

Cookies.set('name', 'value', { expires: 7 });

Functions

set

Creates a new cookie. The first parameter is for the name, and the second for the value. The third parameter is optional and allows you to modify attributes for the new cookie (see the Attributes section below).

// Create an expiring cookie, valid to the path of the current page:
Cookies.set('name', 'value', { expires: 7, path: '' });

get

Returns a single cookie with the specified name, or undefined if the cookie doesn't exist.

Cookies.get('name'); // => 'value'
Cookies.get('nothing'); // => undefined

getAll

Returns an object containing all visible cookies.

Cookies.getAll(); // => { name: 'value' }

remove

Deletes a single cookie by name.

Cookies.remove('name');

IMPORTANT! When removing a cookie, you must pass the exact same path and domain attributes that were used to set the cookie, unless you're using the default attributes.

Cookies.set('name', 'value', { path: '' });
Cookies.remove('name'); // fail!
Cookies.remove('name', { path: '' }); // removed!

Note: Removing a non-existant cookie does not raise an exception or return a value.

parse

Parses a cookie string (e.g. document.cookie) and returns the names/values as an object.

Cookies.parse('c=v; name=value'); // => {c: 'v', name: 'value'}

encode

Takes a name, value, and attributes object and returns an encoded string which can be used to create a new cookie.

Cookies.encode('c', 'v', {secure: true}); // => 'c=v; Secure'

Attributes

expires

Define when the cookie will be removed. Value can be a Number which will be interpreted as days from time of creation or a Date instance. If omitted, the cookie becomes a session cookie.

To create a cookie that expires in less than a day, use a Date object.

Default: Cookie is removed when the user closes the browser.

Examples:

Cookies.set('name', 'value', { expires: 365 });
Cookies.get('name'); // => 'value'
Cookies.remove('name');

let twoHoursFromNow = new Date();
twoHoursFromNow.setHours(twoHoursFromNow.getHours() + 2);
Cookies.set('name', 'value', { expires: twoHoursFromNow });

path

A String indicating the path where the cookie is visible.

Default: /

Examples:

Cookies.set('name', 'value', { path: '' });
Cookies.get('name'); // => 'value'
Cookies.remove('name', { path: '' });

domain

A String indicating a valid domain where the cookie should be visible. The cookie will also be visible to all subdomains.

Default: Cookie is visible only to the domain or subdomain of the page where the cookie was created.

Examples:

Assuming a cookie that is being created on site.com:

Cookies.set('name', 'value', { domain: 'subdomain.site.com' });
Cookies.get('name'); // => undefined (need to read at 'subdomain.site.com')

secure

Either true or false, indicating if the cookie transmission requires a secure protocol (https).

Default: No secure protocol requirement.

Examples:

Cookies.set('name', 'value', { secure: true });
Cookies.get('name'); // => 'value'
Cookies.remove('name');

Encoding

This project is RFC 6265 compliant. Special characters that are not allowed in the cookie name or value are encoded with their UTF-8 Hex equivalent using percent-encoding.

The only character allowed in cookie names or values that is still encoded is the percent (%) character. It is escaped in order to interpret percent input as literal.

Author

Theodore Brown
http://theodorejb.me

License

MIT