use-local-storage-state

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
• Supports SSR
• 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
• My open-source principles aim for quality and maintenance

Usage

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

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

Todo list

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() {
        setTodos([...todos, query])
    }

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

Using the same hook in multiple places

// useTodos.ts
import { createLocalStorageStateHook } from 'use-local-storage-state'
export default createLocalStorageStateHook('todos', [
    'buy milk',
    'do 50 push-ups'
])

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

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

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 local storage 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>}
        </>
    )
}

Reseting to defaults

The setTodos.reset() 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] = useLocalStorageState('todos', [
    'buy milk',
    'do 50 push-ups'
])

setTodos.reset()

API

useLocalStorageState(key, defaultValue?)

Returns [value, setValue, isPersistent]. The first two are the same as useState(). The third(isPersistent) determines if the data is persisted in localStorage or in-memory – 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?)

Returns a hook to be used in multiple places – 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.

Alternatives

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

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