React hook for any Storage compatible API like localStorage, sessionStorage, or a custom one.
MIT License
use-storage-state
React hook for any Storage compatible API like
localStorage
,sessionStorage
, or a custom one.
npm install use-storage-state
Window
storage
event and updates changes across browser tabs, windows, and iframe's. Disable with sync: false
.use-local-storage-state
(400k downloads per month) for the past 4 years.import useStorageState from 'use-storage-state'
export default function Todos() {
const [todos, setTodos] = useStorageState('todos', {
defaultValue: ['buy avocado', 'do 50 push-ups']
})
}
import React, { useState } from 'react'
import useStorageState from 'use-storage-state'
export default function Todos() {
const [todos, setTodos] = useStorageState('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>
))}
</>
)
}
The removeItem()
method will reset the value to its default and will remove the key from the Storage
. It returns to the same state as when the hook was initially created.
import useStorageState from 'use-storage-state'
export default function Todos() {
const [todos, setTodos, removeItem] = useStorageState('todos', {
defaultValue: ['buy avocado']
})
function onClick() {
removeItem()
}
}
If you are hydrating your component (for example, if you are using Next.js), your component might re-render twice. This is behavior specific to React and not to this library. It's caused by the useSyncExternalStore()
hook. There is no workaround.
If you want to know if you are currently rendering the server value you can use this helper function:
function useIsServerRender() {
return useSyncExternalStore(() => {
return () => {}
}, () => false, () => true)
}
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.
const [multiplier, setMultiplier] = useStorageState('multiplier', {
storage: "session" // default is "local"
})
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).
import { memoryStorage } from 'use-storage-state'
memoryStorage.getItem(key)
memoryStorage.setItem(key, value)
memoryStorage.removeItem(key)
use-local-storage-state
— Similar to this hook but for localStorage
only.use-session-storage-state
— Similar to this hook but for sessionStorage
only.local-db-storage
— Tiny wrapper around IndexedDB
that mimics localStorage
API.