cookies-js
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.3 • Public • Published

    Cookies.js

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

    Features
    Browser Compatibility
    Getting the Library
    Use in CommonJS/Node Environments Without window
    A Note About Encoding
    API Reference

    Features

    • RFC6265 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

    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, you might do something like:

    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 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 and HttpUtility.UrlDecode 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 and System.Uri.UnescapeDataString.

    API Reference

    Methods
    Cookies.set(key, value [, options])
    Cookies.get(key)
    Cookies.expire(key [, options])

    Properties
    Cookies.enabled
    Cookies.defaults

    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

    // 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

    // 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

    // 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

    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

    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 '/'

    Install

    npm i cookies-js

    DownloadsWeekly Downloads

    48,734

    Version

    1.2.3

    License

    Public Domain

    Last publish

    Collaborators

    • scotthamper