React useLocalStorage Hook

Ever tried to persist user preferences across page reloads and ended up wrestling with localStorage APIs, JSON serialization bugs, and cross-tab sync issues? You know the drill—manually saving to localStorage on every state change, forgetting to parse JSON back to objects, dealing with storage quota errors. This free open source React useLocalStorage custom hook handles all that persistence complexity so you can focus on building stateful features instead of debugging storage edge cases in your React applications.

useLocalStorage showcase

Persistent state that survives page reloads and syncs across tabs:

"use client";import * as React from "react";import { toast } from "sonner";import { Button } from "@/components/ui/button";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useLocalStorage } from "@/components/ui/shadcn-io/use-local-storage";export default function UseLocalStorageDemo() {  const [counter, setCounter, removeCounter] = useLocalStorage("demo-counter", 0);  const handleIncrement = () => {    setCounter((prev: number) => prev + 1);    toast.success("Counter incremented! 📈", {      description: `Value saved to localStorage: ${counter + 1}`,    });  };  const handleDecrement = () => {    setCounter((prev: number) => prev - 1);    toast.success("Counter decremented! 📉", {      description: `Value saved to localStorage: ${counter - 1}`,    });  };  const handleReset = () => {    removeCounter();    toast.info("Storage cleared", {      description: "Counter reset to initial value",    });  };  return (    <div className="p-6 max-w-sm mx-auto space-y-6">      {/* Header */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Local Storage Demo</h3>        <p className="text-sm text-muted-foreground">Persistent state across sessions</p>      </div>            {/* Counter Display */}      <div className="space-y-2">        <Label className="text-sm font-medium">Persistent Counter</Label>        <div className="bg-muted rounded p-3 min-h-[48px] flex items-center justify-center">          <Badge variant="default" className="text-2xl px-6 py-3 font-mono">            {counter}          </Badge>        </div>      </div>      {/* Control Buttons */}      <div className="grid grid-cols-3 gap-2 min-h-[36px]">        <Button          onClick={handleIncrement}          variant="default"          size="sm"          className="text-sm h-9"        >          +1        </Button>        <Button          onClick={handleDecrement}          variant="outline"          size="sm"          className="text-sm h-9"        >          -1        </Button>        <Button          onClick={handleReset}          variant="secondary"          size="sm"          className="text-sm h-9"        >          Reset        </Button>      </div>      {/* Storage Info */}      <div className="space-y-2">        <Label className="text-sm font-medium">Storage Info</Label>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <code className="text-xs">Key: "demo-counter"</code>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[20px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Refresh page to see persistence • Syncs across tabs        </div>      </div>    </div>  );}

"use client"import { useCallback, useEffect, useState } from "react"import type { Dispatch, SetStateAction } from "react"import { useEventCallback } from "@/components/ui/kibo-ui/use-event-callback"import { useEventListener } from "@/components/ui/kibo-ui/use-event-listener"declare global {  interface WindowEventMap {    "local-storage": CustomEvent  }}type UseLocalStorageOptions<T> = {  serializer?: (value: T) => string  deserializer?: (value: string) => T  initializeWithValue?: boolean}const IS_SERVER = typeof window === "undefined"export function useLocalStorage<T>(  key: string,  initialValue: T | (() => T),  options: UseLocalStorageOptions<T> = {},): [T, Dispatch<SetStateAction<T>>, () => void] {  const { initializeWithValue = true } = options  const serializer = useCallback<(value: T) => string>(    (value) => {      if (options.serializer) {        return options.serializer(value)      }      return JSON.stringify(value)    },    [options],  )  const deserializer = useCallback<(value: string) => T>(    (value) => {      if (options.deserializer) {        return options.deserializer(value)      }      // Support 'undefined' as a value      if (value === "undefined") {        return undefined as unknown as T      }      const defaultValue =        initialValue instanceof Function ? initialValue() : initialValue      let parsed: unknown      try {        parsed = JSON.parse(value)      } catch (error) {        console.error("Error parsing JSON:", error)        return defaultValue // Return initialValue if parsing fails      }      return parsed as T    },    [options, initialValue],  )  // Get from local storage then  // parse stored json or return initialValue  const readValue = useCallback((): T => {    const initialValueToUse =      initialValue instanceof Function ? initialValue() : initialValue    // Prevent build error "window is undefined" but keep working    if (IS_SERVER) {      return initialValueToUse    }    try {      const raw = window.localStorage.getItem(key)      return raw ? deserializer(raw) : initialValueToUse    } catch (error) {      console.warn(`Error reading localStorage key "${key}":`, error)      return initialValueToUse    }  }, [initialValue, key, deserializer])  const [storedValue, setStoredValue] = useState(() => {    if (initializeWithValue) {      return readValue()    }    return initialValue instanceof Function ? initialValue() : initialValue  })  // Return a wrapped version of useState's setter function that ...  // ... persists the new value to localStorage.  const setValue: Dispatch<SetStateAction<T>> = useEventCallback((value) => {    // Prevent build error "window is undefined" but keeps working    if (IS_SERVER) {      console.warn(        `Tried setting localStorage key "${key}" even though environment is not a client`,      )    }    try {      // Allow value to be a function so we have the same API as useState      const newValue = value instanceof Function ? value(readValue()) : value      // Save to local storage      window.localStorage.setItem(key, serializer(newValue))      // Save state      setStoredValue(newValue)      // We dispatch a custom event so every similar useLocalStorage hook is notified      window.dispatchEvent(new StorageEvent("local-storage", { key }))    } catch (error) {      console.warn(`Error setting localStorage key "${key}":`, error)    }  })  const removeValue = useEventCallback(() => {    // Prevent build error "window is undefined" but keeps working    if (IS_SERVER) {      console.warn(        `Tried removing localStorage key "${key}" even though environment is not a client`,      )    }    const defaultValue =      initialValue instanceof Function ? initialValue() : initialValue    // Remove the key from local storage    window.localStorage.removeItem(key)    // Save state with default value    setStoredValue(defaultValue)    // We dispatch a custom event so every similar useLocalStorage hook is notified    window.dispatchEvent(new StorageEvent("local-storage", { key }))  })  useEffect(() => {    setStoredValue(readValue())    // eslint-disable-next-line react-hooks/exhaustive-deps  }, [key])  const handleStorageChange = useCallback(    (event: StorageEvent | CustomEvent) => {      if ((event as StorageEvent).key && (event as StorageEvent).key !== key) {        return      }      setStoredValue(readValue())    },    [key, readValue],  )  // this only works for other documents, not the current one  useEventListener("storage", handleStorageChange)  // this is a custom event, triggered in writeValueToLocalStorage  // See: useLocalStorage()  useEventListener("local-storage", handleStorageChange)  return [storedValue, setValue, removeValue]}export type { UseLocalStorageOptions }

This free open source React hook simplifies browser storage with TypeScript support for modern JavaScript applications. Whether you're building user preferences, form drafts, or session data in your Next.js projects, this React hook keeps your state persistent and synchronized.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-local-storage.json

npx shadcn@latest add https://www.shadcn.io/registry/use-local-storage.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-local-storage.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-local-storage.json

Why most localStorage implementations suck

Look, you could keep calling localStorage.setItem and JSON.stringify everywhere. But then you hit the storage complexity—serialization errors with undefined values, quota exceeded exceptions, cross-tab synchronization headaches, SSR hydration mismatches in React applications.

Most developers manually manage localStorage calls with fragmented try-catch blocks that don't handle all edge cases in TypeScript components. Or they forget about cross-tab synchronization and wonder why user changes in one tab don't appear in others. Some skip SSR considerations entirely and get hydration mismatches with flashing content in Next.js projects.

This React hook provides a useState-like API that automatically handles serialization, error recovery, and cross-tab updates in JavaScript applications. One interface for all your localStorage needs.

Plus it handles all the edge cases—graceful fallbacks when localStorage is disabled, proper SSR initialization, automatic event listening for cross-tab sync in React development. No more scattered try-catch blocks.

This free open source React hook manages persistent storage while you focus on building features. Whether you're creating React applications, Next.js dashboards, or TypeScript components, reliable state persistence keeps your JavaScript development smooth.

Features

• Persistent state that survives page reloads and browser sessions in React applications
• Automatic serialization with JSON serialization/deserialization by default in TypeScript components
• Cross-tab synchronization syncs changes across browser tabs automatically in Next.js projects
• Custom serializers support for dates, complex objects, and custom types in JavaScript development
• SSR compatible with optional initialization for server-side rendering in React frameworks
• Type safety with full TypeScript support and proper generics for modern applications
• Error handling with graceful fallbacks for localStorage errors
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every piece of state in React applications. Regular useState works fine for temporary UI state. But when you need data to persist across sessions or sync across tabs, this React hook handles the complexity in Next.js projects.

Perfect for:

• User preferences - Theme settings, language choices, and UI configurations built with TypeScript
• Form drafts - Save progress on long forms to prevent data loss using React patterns
• Shopping carts - Persist cart items across browser sessions in JavaScript applications
• Session data - User settings and temporary data that should survive refreshes in React components
• Feature flags - Client-side toggles that persist across visits in Next.js applications
• Recently viewed - Track user interactions and browsing history using TypeScript safety

API Reference

useLocalStorage

useLocalStorage<T>(key: string, initialValue: T | (() => T), options?: UseLocalStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void]

UseLocalStorageOptions

Return Value

Returns a tuple with:

• value: The current stored value
• setValue: Function to update the value (same API as useState)
• removeValue: Function to remove the key from localStorage and reset to initial value

Common gotchas

Storage quota limits apply: Browsers limit localStorage size (usually 5-10MB) in React applications. The React hook handles quota exceeded errors gracefully but won't prevent them.

Cross-tab sync has slight delays: Storage events fire when other tabs change values, but there's a small delay in TypeScript components. Don't rely on instant synchronization.

SSR requires careful initialization: Use initializeWithValue: false for SSR to prevent hydration mismatches in Next.js projects, then handle the loading state appropriately.

JSON serialization has limitations: Dates become strings, undefined values are dropped, functions can't be serialized in JavaScript applications. Use custom serializers for complex types.

Storage availability checks: Always handle cases where localStorage might be disabled by browser settings or privacy mode in React frameworks.

Key naming consistency: Use consistent key naming patterns across your application to avoid conflicts and enable easier debugging in TypeScript projects.

Related hooks you will also like

Questions you might have