react-storage-hooks

Custom React hooks for keeping application state in sync with

localStorage

sessionStorage

:book: Familiar API. You already know how to use this library! Replace

useState

useReducer

:sparkles: Fully featured. Automatically stringifies and parses values coming and going to storage, keeps state in sync between tabs by listening to storage events and handles non-straightforward use cases correctly.

:zap: Tiny and fast. Less than 700 bytes gzipped, enforced with

size-limit

:capital_abcd: Completely typed. Written in TypeScript. Type definitions included and verified with

tsd

:muscle: Backed by tests. Full coverage of the API.

Requirements

You need to use version 16.8.0 or greater of React, since that's the first one to include hooks. If you still need to create your application, Create React App is the officially supported way.

Installation

Add the package to your React project:

npm install --save react-storage-hooks

Or with yarn:

yarn add react-storage-hooks

Usage

The

useStorageState

useStorageReducer

useState

useReducer

• Two additional mandatory parameters:

  Storage

  object (

  localStorage

  or

  sessionStorage

  ) and storage key.
• Initial state parameters only apply if there's no data in storage for the provided key. Otherwise data from storage will be used as initial state. Think about it as default or fallback state.
• The array returned by hooks has an extra last item for write errors. It is initially

  undefined

  , and will be updated with

  Error

  objects thrown by

  Storage.setItem

  . However the hook will keep updating state even if new values fail to be written to storage, to ensure that your application doesn't break.

useStorageState

Example

import React from 'react';
import { useStorageState } from 'react-storage-hooks';

function StateCounter() {
  const [count, setCount, writeError] = useStorageState(
    localStorage,
    'state-counter',
    0
  );
  return (
    <>
      
You clicked {count} times
       setCount(count + 1)}>+
       setCount(count - 1)}>-
      {writeError && (
        
Cannot write to localStorage: {writeError.message}
      )}
    >
  );
}

Signature

function useStorageState(
  storage: Storage,
  key: string,
  defaultState?: S | (() => S)
): [S, React.Dispatch>, Error | undefined];

useStorageReducer

Example

import React from 'react';
import { useStorageReducer } from 'react-storage-hooks';

function reducer(state, action) {
  switch (action.type) {
    case 'inc':
      return { count: state.count + 1 };
    case 'dec':
      return { count: state.count - 1 };
    default:
      return state;
  }
}
function ReducerCounter() {
  const [state, dispatch, writeError] = useStorageReducer(
    localStorage,
    'reducer-counter',
    reducer,
    { count: 0 }
  );
  return (
    <>
      
You clicked {state.count} times
       dispatch({ type: 'inc' })}>+
       dispatch({ type: 'dec' })}>-
      {writeError && (
        
Cannot write to localStorage: {writeError.message}
      )}
    >
  );
}

Signature

function useStorageReducer(
  storage: Storage,
  key: string,
  reducer: React.Reducer,
  defaultState: S
): [S, React.Dispatch, Error | undefined];

function useStorageReducer(
  storage: Storage,
  key: string,
  reducer: React.Reducer,
  defaultInitialArg: I,
  defaultInit: (defaultInitialArg: I) => S
): [S, React.Dispatch, Error | undefined];

Advanced usage

Alternative storage objects

The

storage

getItem

setItem

removeItem

Storage

interface Storage {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
}

Server-side rendering (SSR)

This library checks for the existence of the

window

const dummyStorage = {
  getItem: () => null,
  setItem: () => {},
  removeItem: () => {},
};

The important bit here is to have the

getItem

null

Convenience custom hook

If you're using a few hooks in your application with the same type of storage, it might bother you to have to specify the storage object all the time. To alleviate this, you can write a custom hook like this:

import { useStorageState } from 'react-storage-hooks';

export function useLocalStorageState(...args) {
  return useStorageState(localStorage, ...args);
}

And then use it in your components:

import { useLocalStorageState } from './my-hooks';

function Counter() {
  const [count, setCount] = useLocalStorageState('counter', 0);
  // Rest of the component
}

Development

Install development dependencies:

npm install

To set up the examples:

npm run examples:setup

To start a server with the examples in watch mode (reloads whenever examples or library code change):

npm run examples:watch

Tests

Run tests:

npm test

Run tests in watch mode:

npm run test:watch

See code coverage information:

npm run test:coverage

Publish

Go to the

master

git checkout master

Bump the version number:

npm version [major | minor | patch]

Run the release script:

npm run release

All code quality checks will run, the tagged commit generated by

npm version

License

This library is MIT licensed.