useLocalStorage
A React hook for managing localStorage with automatic JSON serialization, type safety, and cross-tab synchronization.
useLocalStorage is a powerful React hook that provides a seamless interface for managing browser localStorage with full TypeScript support. It automatically handles JSON serialization/deserialization, provides type safety, and includes cross-tab synchronization to keep data consistent across multiple browser tabs.
The hook supports complex data types including objects, arrays, and primitive values. It also provides custom serialization options for advanced use cases like Date objects, includes error handling capabilities, and automatically syncs changes across browser tabs using the storage event. This hook uses our own custom hook useEventListener to listen for storage changes across tabs.
A simple example demonstrating primitive value storage with automatic persistence:
const [value, setValue, removeValue] = useLocalStorage(key, initialValue)This example shows how to store and manage basic data types like numbers and strings. The counter persists across page refreshes, and the name input maintains its value even when navigating away and back.
Installation
pnpm dlx shadcn@latest add https://shaddy-docs.vercel.app/r/use-local-storage
Store Complex Objects with Automatic Serialization
Complex object storage with nested properties and automatic serialization:
User Preferences
{
"theme": "light",
"notifications": true,
"language": "en",
"autoSave": false,
"fontSize": 14
}useLocalStorage('user-settings', defaultObject)This example demonstrates storing complex objects with multiple properties. The settings object is automatically serialized to JSON and stored in localStorage, with all changes immediately persisted and synchronized across tabs.
Form Draft Auto-Save
Automatic form data persistence to prevent data loss during editing:
Draft Article
Auto-saves form data as you type - try refreshing the page!This example shows how to implement auto-save functionality for forms. As users type, their input is automatically saved to localStorage, preventing data loss if they accidentally close the tab or refresh the page.
Advanced Features with Custom Serialization
Custom serialization for complex data types and multiple storage patterns:
Advanced Features
Custom Date Serialization
Shopping Cart
This advanced example demonstrates custom serialization for Date objects and managing arrays of complex objects like a shopping cart. It shows how to handle data types that don't serialize well with JSON by default.
API
▸ useLocalStorage<T>(key, initialValue?, options?): [T, Dispatch<SetStateAction<T>>, () => void]
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The localStorage key to store the value under |
initialValue | T | (() => T) | undefined | The initial value or a function to compute it. Defaults to undefined |
options | UseLocalStorageOptions<T> | undefined | Optional configuration for serialization, initialization, and error handling |
Options
The options parameter provides advanced configuration:
| Property | Type | Default | Description |
|---|---|---|---|
serializer | (value: T) => string | undefined | JSON.stringify | Custom function to serialize the value before storing in localStorage |
deserializer | (value: string) => T | undefined | JSON.parse | Custom function to deserialize the value when reading from localStorage |
initializeWithValue | boolean | undefined | true | Whether to initialize with value from localStorage on mount |
onError | (error: Error, key: string) => void | undefined | Console warning | Error handler called when localStorage operations fail |
Returns
Returns a tuple with three elements:
| Index | Type | Description |
|---|---|---|
0 | T | The current value from localStorage or the initial value |
1 | Dispatch<SetStateAction<T>> | A setter function that accepts a value or updater function (same API as useState) |
2 | () => void | A function to remove the item from localStorage and reset to initial value |
Types
type UseLocalStorageOptions<T> = {
serializer?: (value: T) => string
deserializer?: (value: string) => T
initializeWithValue?: boolean
onError?: (error: Error, key: string) => void
}
