use-local-storage-state

React hook that persist data in local storage

Install

npm install use-local-storage-state

Why

Few other libraries also try to abstract the usage of localStorage into a hook. Here are the reasons why you would consider this one:

• Uses JSON.parse() and JSON.stringify() to support non string values
• SSR support
• 100% test coverage. No istanbul ignore
• Handles edge cases – example
• Subscribes to the Window storage event which tracks changes across browser tabs and iframe's
• Aiming for high-quality with my open-source principles

Usage

import useLocalStorageState from 'use-local-storage-state'

const [todos, setTodos] = useLocalStorageState('todos', [
    'buy milk',
    'do 50 push-ups'
])

Todo list example

You can experiment with the example here.

import React, { useState } from 'react'
import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [query, setQuery] = useState('')
    const [todos, setTodos] = useLocalStorageState('todos', ['buy milk'])

    function onClick() {
        setQuery('')
        setTodos([...todos, query])
    }

    return (
        <>
            <input value={query} onChange={e => setQuery(e.target.value)} />
            <button onClick={onClick}>Create</button>
            {todos.map(todo => (<div>{todo}</div>))}
        </>
    )
}

Reseting to defaults

The removeItem() method will reset the value to its default and will remove the key from the localStorage. It returns to the same state as when the hook was initially created.

import useLocalStorageState from 'use-local-storage-state'

const [todos, setTodos, { removeItem }] = useLocalStorageState('todos', [
    'buy milk',
    'do 50 push-ups'
])

function onClick() {
    removeItem()
}

Handling edge cases with isPersistent

There are a few cases when localStorage isn't available. The isPersistent property tells you if the data is persisted in localStorage or in-memory. Useful when you want to notify the user that their data won't be persisted.

import React, { useState } from 'react'
import useLocalStorageState from 'use-local-storage-state'

export default function Todos() {
    const [todos, setTodos, { isPersistent }] = useLocalStorageState('todos', ['buy milk'])

    return (
        <>
            {todos.map(todo => (<div>{todo}</div>))}
            {!isPersistent && <span>Changes aren't currently persisted.</span>}
        </>
    )
}

API

useLocalStorageState(key, defaultValue?)

Returns [value, setValue, { removeItem, isPersistent }]. The first two values are the same as useState(). The third value contains extra properties specific to localStorage:

• removeItem() — example
• isPersistent() — example

key

Type: string

The key used when calling localStorage.setItem(key)and localStorage.getItem(key).

⚠️ Be careful with name conflicts as it is possible to access a property which is already in localStorage that was created from another place in the codebase or in an old version of the application.

defaultValue

Type: any Default: undefined

The initial value of the data. The same as useState(defaultValue) property.

createLocalStorageStateHook(key, defaultValue?)

If you want to have the same data in multiple components in your code use createLocalStorageStateHook() instead of useLocalStorageState(). This avoids:

• maintenance issues with duplicate code that should always be in sync
• conflicts with different default values
• key parameter misspellings

import { createLocalStorageStateHook } from 'use-local-storage-state'

// Todos.tsx
const useTodos = createLocalStorageStateHook('todos', [
    'buy milk',
    'do 50 push-ups'
])
function Todos() {
    const [todos, setTodos] = useTodos()
}

// Popup.tsx
import useTodos from './useTodos'
function Popup() {
    const [todos, setTodos] = useTodos()
}

key

Type: string

The key used when calling localStorage.setItem(key)and localStorage.getItem(key).

⚠️ Be careful with name conflicts as it is possible to access a property which is already in localStorage that was created from another place in the codebase or in an old version of the application.

defaultValue

Type: any Default: undefined

The initial value of the data. The same as useState(defaultValue) property.

Alternatives

These are the best alternatives to my repo I have found so far:

• donavon/use-persisted-state
• imbhargav5/rooks
• dance2die/react-use-localstorage