use-local-storage-state

Install the package via npm depending on your React version.

For React 18 and above:

npm install use-local-storage-state

For React 17 and below:

npm install use-local-storage-state@17

When using SSR (e.g., Next.js), components using useSyncExternalStore (which this library uses) may render twice during hydration. This is standard React behavior. To detect if you are currently rendering the server value, you can use this helper:

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

The useLocalStorageState hook accepts an optional options object of type LocalStorageOptions:

• defaultValue: The initial value if no value exists in localStorage. Similar to useState default value.
• defaultServerValue: The value used during SSR and hydration. If not set, it defaults to defaultValue.
• storageSync: A boolean (default true). If set to false, the hook will not subscribe to the Window storage event, meaning updates will not sync across different tabs, windows, or iframes.
• serializer: An object { stringify, parse } (default JSON). Use this to support complex types like Date, RegExp, or BigInt by providing a library like superjson.

When localStorage is inaccessible (due to browser security settings or quota limits), the library uses an internal inMemoryData Map to store state. This ensures the application remains functional even if persistence is unavailable.

If you need to check if the current state is actually being persisted to disk or just living in memory, check the isPersistent property returned by the hook.

• isPersistent: true -> Data is in localStorage.
• isPersistent: false -> Data is in inMemoryData (fallback).

The removeItem() method, returned in the third element of the hook's return array, removes the key from localStorage and resets the hook's state to its defaultValue.

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

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

    function onClick() {
        removeItem()
    }
}

The useLocalStorageState hook provides a way to persist state in localStorage. It returns an array containing the current value, a setter function, and an object with utility properties.

Basic usage:

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

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

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

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

If localStorage is unavailable (e.g., due to browser settings or errors), the hook falls back to in-memory storage. You can use the isPersistent boolean property to detect this state and notify the user that their changes will not be saved across sessions.

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 key={todo}>{todo}</div>))}
            {!isPersistent && <span>Changes aren't currently persisted.</span>}
        </>
    )
}

The LocalStorageState<T> type defines the shape of the array returned by the hook:

export type LocalStorageState<T> = [
    T,                               // The current state value
    Dispatch<SetStateAction<T>>,     // The setter function
    {
        isPersistent: boolean,      // Whether data is in localStorage or in-memory fallback
        removeItem: () => void      // Function to clear the key from storage
    },
]