use-local-storage-state

React hook that persist data in localStorage

Install

React 18 and above:

1npm install use-local-storage-state

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

1npm 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

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

1import React, { useState } from 'react'
2import useLocalStorageState from 'use-local-storage-state'
3
4export default function Todos() {
5    const [todos, setTodos] = useLocalStorageState('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 React, { useState } from 'react'
2import useLocalStorageState from 'use-local-storage-state'
3
4export default function Todos() {
5    const [todos, setTodos, { isPersistent }] = useLocalStorageState('todos', {
6        defaultValue: ['buy avocado']
7    })
8
9    return (
10        <>
11            {todos.map(todo => (<div>{todo}</div>))}
12            {!isPersistent && <span>Changes aren't currently persisted.</span>}
13        </>
14    )
15}
16

1import useLocalStorageState from 'use-local-storage-state'
2
3export default function Todos() {
4    const [todos, setTodos, { removeItem }] = useLocalStorageState('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

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 state
• isPersistent — 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

• 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.