WebStorage

WebStorage gives you an easy to use binding for working with Web Storage i.e. LocalStorage and SessionStorage.

It can only store data that is serializable and stored as a string, such as via JSON.stringify().

It is semi-controlled, meaning that it will update immediately whenever the data source changes, but only if the changes occur on the current window. Another window may edit the same data source, and if this happens then hocs on a different window will not automatically update. They will contain the new data as soon as they next re-render.

TODO: In future, this will be able to be fully controlled

import WebStorage from 'react-cool-storage/WebStorage';

Config

WebStorage({
    key: string,
    // optional
    method?: string = "localStorage",
    deconstruct?: (data: any) => any,
    reconstruct?: (data: any) => any,
    parse?: (data: string) => any,
    stringify?: (data: any) => string,
    memoize?: boolean = true,
    initialValue?: Object|() => Object
})
  • key : string

    A globally unique key that will be used to store the data in web storage.

  • method ?: string = push

    The Web Storage method to use. Can be ā€œlocalStorageā€ or ā€œsessionStorageā€. Defaults to ā€œlocalStorageā€.

  • deconstruct ?: (data: any) => any

    Can be used to convert data into a serializable format. It is called before ReactRouterStorage stringifies data when a change occurs.

  • reconstruct ?: (data: any) => any

    Can be used to convert data from a serializable format into richer data types. It is called after ReactRouterStorage has parsed its data. It is given the parsed object.

  • parse ?: (data: string) => any = JSON.parse()

    A function that is called on the value to turn it from a string into a data shape. Defaults to JSON.parse().

  • stringify ?: (data: any) => string = JSON.parse()

    A function that is called on the value to turn it from a data shape into a string. Defaults to JSON.stringify().

  • memoize ?: (data: any) => string = JSON.parse()

    When true, the result of parse will be memoized deeply using deep-memo so that references to objects and arrays will remain unchanged unless their values change. This allows parts of the value data object to work seamlessly with React pure components. When false, new objects and arrays will be created every time props change, but if a large amount of data is being parsed then disabling memoization can reduce the computation time of the parsing step. Defaults to true.

  • initialValue ?: Object|() => Object

    If provided a object, or a function that returns an object, initialValue will set the value when the storage mechanism is instanciated.

Resources

WebStorage requires window.localStorage or window.sessionStorage to be available, depending on the method you choose.

This generally means that the browser must support web storage, allow its use, and have sufficient storage space.

Props

WebStorage requires no props.

Outside React

WebStorage doesnā€™t require any props, so you can also access and change WebStorage data outside of React. All ReactCoolStorageHocs that use the WebStorage with the same key will update and stay in sync.

MyWebStorage has been added to the window on this page. Try running MyWebStorage.onChange({foo: "foo"}); in the console and watch the example update at the top of this page.

Example using hooks

import React from 'react';
import ReactCoolStorageHook from 'react-cool-storage';
import WebStorage from 'react-cool-storage/WebStorage';

const useStorage = ReactCoolStorageHook(
    WebStorage({
        key: 'exampleStorage'
    })
);

export default (props) => {
    let webStorage = useStorage(props);

    return <div>
        <label>localStorage data stored under a key of "exampleStorage.foo"</label>
        <input
            value={webStorage.value.foo || ""}
            onChange={(event) => webStorage.onChange({
                foo: event.currentTarget.value
            })}
        />
        <label>localStorage data stored under a key of "exampleStorage.bar"</label>
        <input
            value={webStorage.value.bar || ""}
            onChange={(event) => webStorage.onChange({
                bar: event.currentTarget.value
            })}
        />
    </div>;
};

// also add a WebStorage instance to the window
// to demonstrate usage outside of React

window.MyWebStorage = WebStorage({
    key: 'exampleStorage'
});