React useReadLocalStorage Hook

Ever tried to read localStorage in React and ended up with stale data, broken SSR hydration, or missing cross-tab updates? You know the drill—manually calling localStorage.getItem(), forgetting about JSON.parse errors, dealing with server-side rendering mismatches, missing storage events from other tabs. This free open source React useReadLocalStorage custom hook handles all that localStorage reading complexity so you can focus on building reactive features instead of debugging storage synchronization edge cases in your React applications.

useReadLocalStorage showcase

Reactive localStorage reading with cross-tab synchronization:

"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 { useReadLocalStorage } from "@/components/ui/shadcn-io/use-read-local-storage";export default function UseReadLocalStorageDemo() {  const userTheme = useReadLocalStorage<string>("user-theme");  const cartCount = useReadLocalStorage<number>("cart-items");  const setTheme = (theme: string) => {    localStorage.setItem("user-theme", JSON.stringify(theme));    window.dispatchEvent(new StorageEvent("storage"));    toast.success(`Theme set to ${theme}! 🎨`, {      description: "Hook will automatically update",    });  };  const setCartCount = (count: number) => {    localStorage.setItem("cart-items", JSON.stringify(count));    window.dispatchEvent(new StorageEvent("storage"));    toast.info(`Cart updated! 🛒`, {      description: `${count} items in cart`,    });  };  return (    <div className="p-6 max-w-sm mx-auto space-y-4">      {/* Header */}      <div className="text-center space-y-1">        <h3 className="text-lg font-semibold">Read Local Storage Demo</h3>        <p className="text-sm text-muted-foreground">Reactive localStorage reading</p>      </div>            {/* Current Theme Value */}      <div className="space-y-2">        <Label className="text-sm font-medium">Theme Setting</Label>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <Badge variant={userTheme ? "default" : "secondary"} className="text-sm px-3 py-1">            {userTheme || "None"}          </Badge>        </div>      </div>      {/* Theme Controls */}      <div className="grid grid-cols-2 gap-2 h-8">        <Button          onClick={() => setTheme("light")}          variant="outline"          size="sm"          className="text-xs h-8"        >          Set Light        </Button>        <Button          onClick={() => setTheme("dark")}          variant="outline"          size="sm"          className="text-xs h-8"        >          Set Dark        </Button>      </div>      {/* Instructions */}      <div className="text-center min-h-[16px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Updates automatically • Cross-tab reactive        </div>      </div>    </div>  );}

"use client"import { useCallback, useEffect, useState } from "react"import { useEventListener } from "@/components/ui/kibo-ui/use-event-listener"const IS_SERVER = typeof window === "undefined"type Options<T, InitializeWithValue extends boolean | undefined> = {  deserializer?: (value: string) => T  initializeWithValue: InitializeWithValue}// SSR versionexport function useReadLocalStorage<T>(  key: string,  options: Options<T, false>,): T | null | undefined// CSR versionexport function useReadLocalStorage<T>(  key: string,  options?: Partial<Options<T, true>>,): T | nullexport function useReadLocalStorage<T>(  key: string,  options: Partial<Options<T, boolean>> = {},): T | null | undefined {  let { initializeWithValue = true } = options  if (IS_SERVER) {    initializeWithValue = false  }  const deserializer = useCallback<(value: string) => T | null>(    (value) => {      if (options.deserializer) {        return options.deserializer(value)      }      // Support 'undefined' as a value      if (value === "undefined") {        return undefined as unknown as T      }      let parsed: unknown      try {        parsed = JSON.parse(value)      } catch (error) {        console.error("Error parsing JSON:", error)        return null      }      return parsed as T    },    [options],  )  // Get from local storage then  // parse stored json or return initialValue  const readValue = useCallback((): T | null => {    // Prevent build error "window is undefined" but keep keep working    if (IS_SERVER) {      return null    }    try {      const raw = window.localStorage.getItem(key)      return raw ? deserializer(raw) : null    } catch (error) {      console.warn(`Error reading localStorage key "${key}":`, error)      return null    }  }, [key, deserializer])  const [storedValue, setStoredValue] = useState(() => {    if (initializeWithValue) {      return readValue()    }    return undefined  })  // Listen if localStorage changes  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}export type { Options }

This free open source React hook simplifies localStorage access with TypeScript support for modern JavaScript applications. Whether you're building user preferences, authentication state, or shopping cart displays in your Next.js projects, this React hook keeps your localStorage data reactive and reliable.

Installation

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

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

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

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

Why most localStorage reading implementations suck

Look, you could keep calling localStorage.getItem() and JSON.parse() manually. But then you hit the localStorage complexity—stale data when other tabs update values, broken SSR hydration, performance issues from repeated storage access, error handling for malformed JSON in React applications.

Most developers call localStorage.getItem() on every render, causing unnecessary performance overhead in TypeScript components. Or they forget about storage events and miss updates when other tabs change values, leading to stale data and inconsistent UI states. Some skip SSR considerations entirely and get hydration mismatches when localStorage values differ from server-rendered content in Next.js projects.

This React hook uses optimized storage event listening under the hood, with automatic cross-tab synchronization and proper SSR handling in JavaScript applications. The browser handles all the storage events, plus you get type-safe deserialization and error recovery in one call.

Plus it handles all the edge cases—SSR compatibility with controlled hydration, automatic JSON parsing with fallbacks, storage event coordination across browser tabs in React development. No more stale localStorage reads or broken server-side rendering.

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

Features

• Read-only access providing lightweight alternative to full localStorage hooks in React applications
• Automatic updates responding to localStorage changes across tabs and windows in TypeScript components
• SSR compatible with optional initialization for server-side rendering safety in Next.js projects
• Custom deserialization supporting custom deserializer functions for complex types in JavaScript development
• Type safety with full TypeScript support and proper generic constraints for React frameworks
• Error handling providing graceful fallbacks for localStorage access errors in modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every localStorage need in React applications. If you're also writing to localStorage, use the full useLocalStorage hook. But when you need read-only access with reactive updates and optimal performance, this React hook delivers in Next.js projects.

Perfect for:

• User preference displays - Show current theme, language, or layout settings built with TypeScript
• Authentication status - Display login state and user information from tokens using React patterns
• Shopping cart indicators - Show cart item counts and totals in navigation in JavaScript applications
• Feature flag reading - Check enabled features without modification capabilities in React components
• Recent activity - Display browsing history or recently viewed items in Next.js applications
• Form draft recovery - Show saved draft indicators without editing the drafts using TypeScript safety

API Reference

useReadLocalStorage

useReadLocalStorage<T>(
  key: string,
  options?: UseReadLocalStorageOptions<T>
): T | null | undefined

Options

Return Value

Returns the stored value of type T, null if key doesn't exist or error occurs, or undefined during SSR when initializeWithValue: false.

Common gotchas

Cross-tab updates are automatic: The React hook listens for storage events and updates when localStorage changes in other browser tabs in React applications. This keeps your UI synchronized but means components will re-render when external changes occur.

SSR requires careful initialization: Use initializeWithValue: false to prevent hydration mismatches in TypeScript components. The React hook will return undefined initially and update with the stored value after client hydration.

Error handling returns null: If localStorage access fails (disabled storage, quota exceeded, malformed JSON), the hook returns null in Next.js projects. Always check for null values in your components.

Read-only hook for performance: This React hook is optimized for reading only in JavaScript applications. If you need to write localStorage values, use the full useLocalStorage hook instead of combining this with manual localStorage.setItem() calls.

Storage event timing: Storage events are asynchronous and may not fire immediately when localStorage changes in React frameworks. Handle loading states appropriately for better user experience.

Deserialization error handling: Custom deserializers should handle malformed data gracefully in TypeScript projects. The hook returns null when deserialization fails, preventing application crashes.

Related hooks you will also like

Questions you might have