use-storage-state

React hook for any Storage compatible API like localStorage, sessionStorage, or a custom one.

Install

1npm install use-storage-state

Why

• SSR support.
• Production ready. Used broadly across Twitch web properties.
• Works with React 19 and React 18 concurrent rendering.
• Handles the Window storage event and updates changes across browser tabs, windows, and iframe's. Disable with sync: false.
• I also actively maintain use-local-storage-state (400k downloads per month) for the past 4 years.
• Aiming for high-quality with my open-source principles.

Usage

1import useStorageState from 'use-storage-state'
2
3export default function Todos() {
4    const [todos, setTodos] = useStorageState('todos', {
5        defaultValue: ['buy avocado', 'do 50 push-ups']
6    })
7}

1import React, { useState } from 'react'
2import useStorageState from 'use-storage-state'
3
4export default function Todos() {
5    const [todos, setTodos] = useStorageState('todos', {
6        defaultValue: ['buy avocado']
7    })
8    const [query, setQuery] = useState('')
9
10    function onClick() {
11        setQuery('')
12        setTodos([...todos, query])
13    }
14
15    return (
16        <>
17            <input value={query} onChange={e => setQuery(e.target.value)} />
18            <button onClick={onClick}>Create</button>
19            {todos.map(todo => (
20                <div>{todo}</div>
21            ))}
22        </>
23    )
24}
25

1import useStorageState from 'use-storage-state'
2
3export default function Todos() {
4    const [todos, setTodos, removeItem] = useStorageState('todos', {
5        defaultValue: ['buy avocado']
6    })
7
8    function onClick() {
9        removeItem()
10    }
11}

1function useIsServerRender() {
2  return useSyncExternalStore(() => {
3    return () => {}
4  }, () => false, () => true)
5}

API

useStorageState(key: string, options?: StorageStateOptions)

Returns [value, setValue, removeItem] when called. The first two values are the same as useState(). The third value calls Storage.removeItem() and resets the hook to it's default state.

key

Type: string

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

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

options.defaultValue

Type: any

Default: undefined

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

options.storage

Type: "local" | "session" | Storage | undefined

Default: "local"

You can set localStorage, sessionStorage, or other any Storage compatible class.

Note: Prefer to use the "local" and "session" literals instead of localStorage or sessionStorage objects directly, as both can throw an error when accessed if user has configured the browser to not store any site data.

1const [multiplier, setMultiplier] = useStorageState('multiplier', {
2    storage: "session" // default is "local"
3})

options.memoryFallback

Type: boolean

Default: true

If you pass undefined to the storage option or localStorage or sessionStorage throw an error when accessed (possible when the browser is configured to not store any site data on device), the library uses a memory storage fallback to avoid your app from breaking completely. You can disable this behavior by setting this option to false.

options.sync

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.

options.storeDefault

Type: boolean

Default: false

Setting to true calls storage.setItem() for the default value so the default value is persisted in Storage after the first render of the hook.

options.serializer

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.

memoryStorage

The library exports a memoryStorage object that's used when the memoryFallback option is set to true (the default).

1import { memoryStorage } from 'use-storage-state'
2
3memoryStorage.getItem(key)
4memoryStorage.setItem(key, value)
5memoryStorage.removeItem(key)

Related

• use-local-storage-state — Similar to this hook but for localStorage only.
• use-session-storage-state — Similar to this hook but for sessionStorage only.
• use-db — Similar to this hook but for IndexedDB.
• local-db-storage — Tiny wrapper around IndexedDB that mimics localStorage API.