use-local-storage-state

React hook that persist data in localStorage

React 18 and above:

npm install use-local-storage-state

⚠️ React 17 and below. For docs, go to the react-17 branch.

npm install use-local-storage-state@17

• Actively maintained for the past 4 years — see contributors page.
• Production ready.
• 689 B (brotlied).
• SSR support.
• Works with React 18 concurrent rendering and React 19.
• Handles the Window storage event and updates changes across browser tabs, windows, and iframe's. Disable with storageSync: false.
• In-memory fallback when localStorage throws an error and can't store the data. Provides a isPersistent API to let you notify the user their data isn't currently being stored.
• Aiming for high-quality with my open-source principles.

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

export default function Todos() {
    const [todos, setTodos] = useLocalStorageState('todos', {
        defaultValue: ['buy avocado', 'do 50 push-ups']
    })
}

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

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

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

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

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

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

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

export default function Todos() {
    const [todos, setTodos, { removeItem }] = useLocalStorageState('todos', {
        defaultValue: ['buy avocado']
    })

    function onClick() {
        removeItem()
    }
}

function useIsServerRender() {
  return useSyncExternalStore(() => {
    return () => {}
  }, () => false, () => true)
}

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

• removeItem() — calls localStorage.removeItem(key) and resets the hook to it's default state
• isPersistent — boolean property that returns false if localStorage is throwing an error and the data is stored only in-memory

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.

Type: any

Default: undefined

The default value. You can think of it as the same as useState(defaultValue).

Type: any

Default: undefined

The default value while server-rendering and hydrating. If not set, it will use defaultValue option instead. Set only if you want it to be different than the client value.

Type: boolean

Default: true

Setting to false doesn't subscribe to the Window storage event. If you set to false, updates won't be synchronized across tabs, windows and iframes.

Type: { stringify, parse }

Default: JSON

JSON does not serialize Date, Regex, or BigInt data. You can pass in superjson or other JSON-compatible serialization library for more advanced serialization.

• use-storage-state — Supports localStorage, sessionStorage, and any other Storage compatible API.
• use-session-storage-state — A clone of this library but for sessionStorage.
• use-db — Similar to this hook but for IndexedDB.
• local-db-storage — Tiny wrapper around IndexedDB that mimics localStorage API.