useLocalStorage — useState respaldado por localStorage con sincronización entre pestañas

Receta

import { useState, useEffect, useCallback } from "react";
 
function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void, () => void] {
  // El inicializador lazy lee del almacenamiento solo una vez
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === "undefined") return initialValue;
    try {
      const item = localStorage.getItem(key);
      return item !== null ? (JSON.parse(item) as T) : initialValue;
    } catch {
      return initialValue;
    }
  });
 
  // Persiste en localStorage cuando el valor o la clave cambian
  useEffect(() => {
    if (typeof window === "undefined") return;
    try {
      localStorage.setItem(key, JSON.stringify(storedValue));
    } catch {
      // Cuota de almacenamiento excedida o no disponible
    }
  }, [key, storedValue]);
 
  // Sincroniza entre pestañas a través del evento storage
  useEffect(() => {
    if (typeof window === "undefined") return;
 
    const handleStorage = (e: StorageEvent) => {
      if (e.key !== key) return;
      if (e.newValue === null) {
        setStoredValue(initialValue);
      } else {
        try {
          setStoredValue(JSON.parse(e.newValue) as T);
        } catch {
          // Ignora JSON malformado
        }
      }
    };
 
    window.addEventListener("storage", handleStorage);
    return () => window.removeEventListener("storage", handleStorage);
  }, [key, initialValue]);
 
  // Setter que coincide con la firma de useState (valor o fn actualizadora)
  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => {
      setStoredValue((prev) => {
        const nextValue =
          value instanceof Function ? value(prev) : value;
        return nextValue;
      });
    },
    []
  );
 
  // Elimina la clave del almacenamiento y restablece a inicial
  const remove = useCallback(() => {
    if (typeof window !== "undefined") {
      localStorage.removeItem(key);
    }
    setStoredValue(initialValue);
  }, [key, initialValue]);
 
  return [storedValue, setValue, remove];
}

Cuándo usarlo: Deseas que el estado del componente sobreviva a las actualizaciones de página, y opcionalmente se mantenga sincronizado en las pestañas del navegador, sin necesidad de una biblioteca externa.

Ejemplo funcional

"use client";
 
function ThemeToggle() {
  const [theme, setTheme, removeTheme] = useLocalStorage<"light" | "dark">(
    "app-theme",
    "light"
  );
 
  return (
    <div>
      <p>Tema actual: {theme}</p>
      <button onClick={() => setTheme((t) => (t === "light" ? "dark" : "light"))}>
        Alternar tema
      </button>
      <button onClick={removeTheme}>Restablecer predeterminado</button>
    </div>
  );
}
 
function FormDraft() {
  const [draft, setDraft] = useLocalStorage("form-draft", {
    name: "",
    email: "",
  });
 
  return (
    <form>
      <input
        value={draft.name}
        onChange={(e) => setDraft((d) => ({ ...d, name: e.target.value }))}
        placeholder="Name"
      />
      <input
        value={draft.email}
        onChange={(e) => setDraft((d) => ({ ...d, email: e.target.value }))}
        placeholder="Email"
      />
      <p>Borrador guardado automáticamente en localStorage</p>
    </form>
  );
}

Lo que esto demuestra:

• Almacenamiento seguro de tipos con tipo de unión "light" | "dark"
• Sintaxis de función actualizadora (prev) => next como en useState
• Almacenamiento de objetos con serialización JSON
• Función remove para borrar la clave y restablecer el estado
• Abrir dos pestañas muestra el tema sincronizándose a través del evento storage

Análisis profundo

Cómo funciona

• Inicializador lazy: La callback de useState lee de localStorage solo en el primer renderizado, evitando lecturas redundantes en cada re-renderizado.
• Protección de SSR: Cada acceso a window está protegido por verificaciones typeof window === "undefined", de modo que el hook devuelve initialValue durante la renderización del lado del servidor sin desincronización de hidratación.
• Ciclo JSON: Los valores se serializan con JSON.stringify y se deserializan con JSON.parse. Esto maneja primitivos, arrays y objetos simples.
• Sincronización entre pestañas: El evento storage se dispara en otras pestañas cuando la misma clave cambia. El listener actualiza el estado local para que coincida.
• Actualizaciones funcionales: El setter acepta un valor directo o una función (prev) => next, reflejando la API de useState.

Parámetros y valores de retorno

Variaciones

Con expiración: Añade un TTL almacenando { value, expiresAt } y verificando al leer:

const item = JSON.parse(raw);
if (item.expiresAt && Date.now() > item.expiresAt) {
  localStorage.removeItem(key);
  return initialValue;
}
return item.value;

Con serializador personalizado: Acepta opciones serialize y deserialize para datos no JSON (por ejemplo, superjson para objetos Date, Map, Set).

Variante de sessionStorage: Cambia localStorage por sessionStorage — la API es idéntica, pero los datos se borran cuando se cierra la pestaña.

Notas de TypeScript

• El genérico T fluye desde initialValue al estado almacenado y al setter, proporcionando inferencia de tipo completa.
• Los tipos de unión como "light" | "dark" estrechan la entrada del setter automáticamente.
• Para tipos complejos, pasa el genérico explícitamente: useLocalStorage<User>("user", defaultUser).

Puntos débiles

• Valores no serializables — Las funciones, Symbols, undefined, y objetos circulares no pueden sobrevivir a JSON.stringify. Solución: Solo almacena datos serializables simples. Usa superjson para Date, Map, Set.
• Cuota de almacenamiento excedida — Los navegadores limitan localStorage a alrededor de 5 MB. Solución: El try/catch en el efecto de escritura lo maneja silenciosamente; considera advertir al usuario.
• El evento storage solo se dispara en otras pestañas — La misma pestaña que escribió el valor no recibe un evento storage. Solución: Este hook maneja las actualizaciones de la misma pestaña a través de setState; la sincronización entre pestañas se maneja mediante el event listener.
• Colisiones de claves — Múltiples aplicaciones en el mismo origen comparten localStorage. Solución: Prefija las claves con un espacio de nombres de la aplicación como myapp:theme.
• Desincronización de hidratación — Si el servidor renderiza con initialValue pero el cliente lee un valor diferente del almacenamiento, ocurre una desincronización. Solución: El inicializador lazy solo se ejecuta en el cliente. Para frameworks SSR, el renderizado inicial usa initialValue, luego se actualiza después de la hidratación.

Alternativas

Preguntas frecuentes

const [theme, setTheme] = useLocalStorage("myapp:theme", "light");

useLocalStorage<"light" | "dark">("theme", "light");

Relacionado

• useToggle — combina con localStorage para conmutadores persistentes
• useMediaQuery — detecta la preferencia del tema del sistema
• useState — la primitiva subyacente