useLocalStorage

A React hook built on top of useSyncExternalStore that synchronizes state with localStorage, providing reactive updates across browser tabs and windows.

Key Features

• Cross-tab synchronization: Changes in one tab automatically update all other tabs
• Infinite loop prevention: Uses string snapshots internally to prevent React re-render loops
• Automatic cleanup: Setting null, undefined, or "" removes the item from localStorage
• Error handling: Falls back to initialValue if JSON parsing fails

Important Limitations

• No SSR support: This hook must only be called on the client side. The server snapshot always returns null, which will cause the initial value to be used during hydration.
• JSON serialization: Only values that can be serialized with JSON.stringify() are supported. Functions, undefined, and circular references cannot be stored.

How it works

1. Uses useSyncExternalStore to subscribe to localStorage changes
2. Listens to native storage events (for changes from other tabs)
3. Dispatches custom local-storage-change events (for changes in the current tab)
4. Returns a string snapshot to prevent infinite loops, then parses it in a useMemo

Installation

npx shadcn@latest add https://mhl5.vercel.app/r/useLocalStorage.json

Usage

import { useLocalStorage } from "@/src/hooks/useLocalStorage";

const [value, setValue] = useLocalStorage("key", "default value");