use-local-storage-state
React hook that persist data in localStorage
Install
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
Why
- 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.
Usage
import useLocalStorageState from 'use-local-storage-state'
export default function Todos() {
const [todos, setTodos] = useLocalStorageState('todos', {
defaultValue: ['buy avocado', 'do 50 push-ups']
})
}
Todo list example
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>
))}
</>
)
}
Notify the user when localStorage
isn't saving the data using the isPersistent
property
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', {
defaultValue: ['buy avocado']
})
return (
<>
{todos.map(todo => (<div>{todo}</div>))}
{!isPersistent && <span>Changes aren't currently persisted.</span>}
</>
)
}
Removing the data from localStorage
and resetting to the default
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'
export default function Todos() {
const [todos, setTodos, { removeItem }] = useLocalStorageState('todos', {
defaultValue: ['buy avocado']
})
function onClick() {
removeItem()
}
}
Why my component renders twice?
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. This has been discussed in the issues: https://github.com/astoilkov/use-local-storage-state/issues/56.
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)
}
API
useLocalStorageState(key: string, options?: LocalStorageOptions)
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 stateisPersistent
— boolean
property that returns false
if localStorage
is throwing an error and the data is stored only in-memory
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.
options.defaultValue
Type: any
Default: undefined
The default value. You can think of it as the same as useState(defaultValue)
.
options.defaultServerValue
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.
options.storageSync
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.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.
Related