useLocalStorage
Overview
useLocalStorage exposes local storage as a typed external store, including same-page subscribers, cross-document storage events, and recoverable errors.
Signature
function useLocalStorage<T>(
key: string,
initialValue: T | (() => T),
options?: { serialize?: (value: T) => string; deserialize?: (raw: string) => T },
): { value: T; error: unknown; setValue: (next: SetStateAction<T>) => void; remove: () => void };Parameters
key identifies the item. initialValue is captured once and may be lazy. Serialization defaults to JSON; custom serializer and deserializer must agree.
Returns
The current value, the latest access or codec error, a functional setValue, and remove.
Behavior
Failed reads keep the current value and report the error. Failed writes do not replace the current value. remove restores the captured initial value. Subscribers for a key share the raw storage channel and native listener while applying their own captured initial value and decoder.
SSR / RSC
The server snapshot uses initialValue; storage is read only when a browser is available. Use a deterministic initial value in a Client Component.
Example
Composition
Display error when persistence matters. Keep security-sensitive or server-authoritative data out of browser storage.