useReadLocalStorage

React hook that reads a value from localStorage with automatic updates, cross-tab synchronization, and SSR compatibility.

Loading component...

"use client"import { useState } from "react"import { useReadLocalStorage } from "@/components/ui/shadcn-io/use-read-local-storage"export function UseReadLocalStorageDemo() {  const [inputKey, setInputKey] = useState("demo-key")    // Read values from localStorage for different keys  const demoValue = useReadLocalStorage<string>("demo-key")  const userPrefs = useReadLocalStorage<{ theme: string; lang: string }>("user-prefs")  const count = useReadLocalStorage<number>("counter")  const customValue = useReadLocalStorage<string>(inputKey)  // Function to set some example values for demonstration  const setExampleValues = () => {    localStorage.setItem("demo-key", JSON.stringify("Hello World"))    localStorage.setItem("user-prefs", JSON.stringify({ theme: "dark", lang: "en" }))    localStorage.setItem("counter", JSON.stringify(42))    localStorage.setItem("custom-key", JSON.stringify("Custom Value"))    // Trigger storage events to update hooks    window.dispatchEvent(new StorageEvent("local-storage"))  }  const clearStorage = () => {    localStorage.removeItem("demo-key")    localStorage.removeItem("user-prefs")    localStorage.removeItem("counter")    localStorage.removeItem("custom-key")    localStorage.removeItem(inputKey)    window.dispatchEvent(new StorageEvent("local-storage"))  }  return (    <div className="space-y-4 p-6">      <div className="flex gap-2">        <button          onClick={setExampleValues}          className="rounded bg-primary px-3 py-2 text-sm text-primary-foreground hover:bg-primary/90"        >          Set Example Data        </button>        <button          onClick={clearStorage}          className="rounded border border-input bg-background px-3 py-2 text-sm hover:bg-accent hover:text-accent-foreground"        >          Clear All        </button>      </div>      <div className="space-y-3 text-sm">        <div className="grid grid-cols-[120px_1fr] gap-2 items-center p-2 bg-muted rounded">          <span className="font-medium">demo-key:</span>          <span className="font-mono text-xs">            {demoValue ? `"${demoValue}"` : "null"}          </span>        </div>        <div className="grid grid-cols-[120px_1fr] gap-2 items-center p-2 bg-muted rounded">          <span className="font-medium">user-prefs:</span>          <span className="font-mono text-xs">            {userPrefs ? JSON.stringify(userPrefs) : "null"}          </span>        </div>        <div className="grid grid-cols-[120px_1fr] gap-2 items-center p-2 bg-muted rounded">          <span className="font-medium">counter:</span>          <span className="font-mono text-xs">            {count !== null ? count.toString() : "null"}          </span>        </div>        <div className="grid grid-cols-[120px_1fr] gap-2 items-center p-2 bg-muted rounded">          <div className="space-y-1">            <input              type="text"              value={inputKey}              onChange={(e) => setInputKey(e.target.value)}              placeholder="Enter key..."              className="w-full px-2 py-1 text-xs border rounded"            />          </div>          <span className="font-mono text-xs">            {customValue ? `"${customValue}"` : "null"}          </span>        </div>      </div>      <div className="text-xs text-muted-foreground bg-muted p-3 rounded">        <p><strong>Try this:</strong> Set example data, then open another tab with this page. Change localStorage in one tab and watch values update in both!</p>      </div>    </div>  )}export default UseReadLocalStorageDemo

"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 }

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

Features

Read-only access - Lightweight alternative to useLocalStorage for read-only scenarios
Automatic updates - Responds to localStorage changes across tabs and windows
SSR compatible - Optional initialization for server-side rendering
Custom deserialization - Support for custom deserializer functions
Type safety - Full TypeScript support with proper generics
Error handling - Graceful fallbacks for localStorage errors
Cross-tab sync - Updates when localStorage changes in other tabs

Usage

import { useReadLocalStorage } from "@/hooks/use-read-local-storage"

function UserProfile() {
  // Assuming a value was set in localStorage with this key
  const userPreferences = useReadLocalStorage<{ theme: string; lang: string }>("user-prefs")

  return (
    <div>
      {userPreferences && (
        <>
          <p>Theme: {userPreferences.theme}</p>
          <p>Language: {userPreferences.lang}</p>
        </>
      )}
    </div>
  )
}

API Reference

useReadLocalStorage

// Client-side version
useReadLocalStorage<T>(key: string, options?: Partial<Options<T, true>>): T | null

// SSR version
useReadLocalStorage<T>(key: string, options: Options<T, false>): T | null | undefined

Options

Property	Type	Default	Description
`deserializer`	`(value: string) => T`	`JSON.parse`	Custom function to deserialize the stored string value
`initializeWithValue`	`boolean`	`true`	Whether to initialize with localStorage value (set to `false` for SSR)

Return Value

T | null - The stored value or null if key doesn't exist or error occurs
T | null | undefined - When initializeWithValue: false, may return undefined during SSR

Usage Examples

Basic Reading

const darkMode = useReadLocalStorage<boolean>("darkMode")
const username = useReadLocalStorage<string>("username")
const settings = useReadLocalStorage<{ notifications: boolean }>("settings")

return (
  <div className={darkMode ? "dark" : "light"}>
    <p>Welcome, {username || "Guest"}</p>
    <p>Notifications: {settings?.notifications ? "On" : "Off"}</p>
  </div>
)

Custom Deserializer

const lastVisit = useReadLocalStorage<Date>("lastVisit", {
  deserializer: (value) => new Date(value)
})

return (
  <div>
    {lastVisit && <p>Last visit: {lastVisit.toLocaleDateString()}</p>}
  </div>
)

SSR Compatible

const theme = useReadLocalStorage<string>("theme", {
  initializeWithValue: false
})

// During SSR, theme will be undefined
// After hydration, theme will be the stored value or null

return (
  <div className={theme || "default-theme"}>
    Content
  </div>
)

Reading User Preferences

function AppSettings() {
  const userSettings = useReadLocalStorage<{
    theme: "light" | "dark"
    language: string
    notifications: boolean
    autoSave: boolean
  }>("app-settings")

  if (!userSettings) {
    return <div>Loading user settings...</div>
  }

  return (
    <div>
      <h2>Current Settings</h2>
      <ul>
        <li>Theme: {userSettings.theme}</li>
        <li>Language: {userSettings.language}</li>
        <li>Notifications: {userSettings.notifications ? "Enabled" : "Disabled"}</li>
        <li>Auto-save: {userSettings.autoSave ? "On" : "Off"}</li>
      </ul>
    </div>
  )
}

Watching Shopping Cart

function CartIndicator() {
  const cartItems = useReadLocalStorage<Array<{ id: string; name: string; qty: number }>>("cart-items")
  
  const totalItems = cartItems?.reduce((sum, item) => sum + item.qty, 0) || 0

  return (
    <button>
      🛒 Cart ({totalItems})
    </button>
  )
}

Reading Authentication Token

function AuthStatus() {
  const token = useReadLocalStorage<string>("auth-token")
  const user = useReadLocalStorage<{ name: string; email: string }>("user-data")

  return (
    <div>
      {token ? (
        <div>
          <p>✅ Logged in as {user?.name}</p>
          <p>Email: {user?.email}</p>
        </div>
      ) : (
        <p>❌ Not logged in</p>
      )}
    </div>
  )
}

Multiple Storage Keys

function Dashboard() {
  const theme = useReadLocalStorage<string>("theme")
  const layout = useReadLocalStorage<"grid" | "list">("dashboard-layout")  
  const filters = useReadLocalStorage<string[]>("active-filters")
  const lastSync = useReadLocalStorage<Date>("last-sync", {
    deserializer: (value) => new Date(value)
  })

  return (
    <div className={`theme-${theme || "default"}`}>
      <div className={layout === "grid" ? "grid-layout" : "list-layout"}>
        <p>Active filters: {filters?.join(", ") || "None"}</p>
        <p>Last sync: {lastSync?.toLocaleString() || "Never"}</p>
      </div>
    </div>
  )
}

Common Use Cases

Reading user preferences - Theme, language, layout settings
Authentication state - Reading stored tokens or user data
Shopping cart display - Showing cart item count from localStorage
Feature flags - Reading enabled/disabled features
Recently viewed items - Displaying browsing history
Form auto-save - Reading saved draft content
Analytics settings - Reading consent and tracking preferences
App configuration - Reading stored configuration options

Comparison with useLocalStorage

Feature	useReadLocalStorage	useLocalStorage
Read values	✅	✅
Write values	❌	✅
Bundle size	Smaller	Larger
Use case	Read-only scenarios	Read/write scenarios
Performance	Optimized for reading	General purpose

Implementation Details

Uses useEventListener to listen for both storage and custom local-storage events
Automatically updates when localStorage changes in the current tab or other tabs
Uses JSON.parse by default but supports custom deserializer functions
Handles localStorage errors gracefully by returning null
Supports server-side rendering with initializeWithValue: false
Re-reads value whenever the key changes
Provides type safety with TypeScript generics

Best Practices

Use for read-only scenarios: When you only need to read localStorage values
Handle null values: Always check if the returned value is null
Provide fallbacks: Use default values when localStorage is empty
Custom deserializers: Use for complex data types like dates
SSR considerations: Set initializeWithValue: false for server-side rendering
Type safety: Always specify the generic type for better TypeScript support

useReadLocalStorage

Reactuse-read-local-storage

On this page