js-cookie

JavaScript Cookie

A simple, lightweight JavaScript API for handling cookies

• Works in all browsers
• Accepts any character
• Heavily tested
• No dependency
• Supports ES modules
• Supports AMD/CommonJS
• RFC 6265 compliant
• Useful Wiki
• Enable custom encoding/decoding
• < 800 bytes gzipped!

👉👉 If you’re viewing this at https://github.com/js-cookie/js-cookie, you’re reading the documentation for the master branch. View documentation for the latest release. 👈👈

Installation

NPM

JavaScript Cookie supports npm under the name js-cookie.

$ npm i js-cookie

The npm package has a module field pointing to an ES module variant of the library, mainly to provide support for ES module aware bundlers, whereas its browser field points to an UMD module for full backward compatibility.

Direct download

Starting with version 3 releases are distributed with two variants of this library, an ES module as well as an UMD module.

Note the different extensions: .mjs denotes the ES module, whereas .js is the UMD one.

Example for how to load the ES module in a browser:

<script type="module" src="/path/to/js.cookie.mjs"></script>
<script type="module">
  import Cookies from '/path/to/js.cookie.mjs'

  Cookies.set('foo', 'bar')
</script>

Not all browsers support ES modules natively yet. For this reason the npm package/release provides both the ES and UMD module variant and you may want to include the ES module along with the UMD fallback to account for this:

<script type="module" src="/path/to/js.cookie.mjs"></script>
<script nomodule defer src="/path/to/js.cookie.js"></script>

Here we’re loading the nomodule script in a deferred fashion, because ES modules are deferred by default. This may not be strictly necessary depending on how you’re using the library.

CDN

Alternatively, include it via jsDelivr CDN.

ES Module

Example for how to import the ES module from another module:

import Cookies from 'js-cookie'

Cookies.set('foo', 'bar')

Basic Usage

Create a cookie, valid across the entire site:

Cookies.set('name', 'value')

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

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

Create an expiring cookie, valid to the path of the current page:

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

Read cookie:

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

Read all visible cookies:

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

Note: It is not possible to read a particular cookie by passing one of the cookie attributes (which may or may not have been used when writing the cookie in question):

Cookies.get('foo', { domain: 'sub.example.com' }) // `domain` won't have any effect...!

The cookie with the name foo will only be available on .get() if it’s visible from where the code is called; the domain and/or path attribute will not have an effect when reading.

Delete cookie:

Cookies.remove('name')

Delete a cookie valid to the path of the current page:

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

IMPORTANT! When deleting a cookie and you’re not relying on the default attributes, you must pass the exact same path and domain attributes that were used to set the cookie:

Cookies.remove('name', { path: '', domain: '.yourdomain.com' })

Note: Removing a nonexistent cookie neither raises any exception nor returns any value.