useLocalStorage - useState com suporte do localStorage e sincronização entre abas

Receita

import { useState, useEffect, useCallback } from "react";
 
function useLocalStorage<T>(
  key: string,
  initialValue: T
): [T, (value: T | ((prev: T) => T)) => void, () => void] {
  // O inicializador preguiçoso lê do armazenamento apenas uma 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 no localStorage sempre que o valor ou a chave mudam
  useEffect(() => {
    if (typeof window === "undefined") return;
    try {
      localStorage.setItem(key, JSON.stringify(storedValue));
    } catch {
      // Cota de armazenamento excedida ou indisponível
    }
  }, [key, storedValue]);
 
  // Sincroniza entre abas via evento de armazenamento
  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 corresponde à assinatura do useState (valor ou função atualizadora)
  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => {
      setStoredValue((prev) => {
        const nextValue =
          value instanceof Function ? value(prev) : value;
        return nextValue;
      });
    },
    []
  );
 
  // Remove a chave do armazenamento e redefine para o valor inicial
  const remove = useCallback(() => {
    if (typeof window !== "undefined") {
      localStorage.removeItem(key);
    }
    setStoredValue(initialValue);
  }, [key, initialValue]);
 
  return [storedValue, setValue, remove];
}

Quando usar isso: Você quer que o estado do componente sobreviva a atualizações de página e, opcionalmente, permaneça sincronizado entre abas do navegador, sem precisar de uma biblioteca externa.

Exemplo Funcional

"use client";
 
function ThemeToggle() {
  const [theme, setTheme, removeTheme] = useLocalStorage<"light" | "dark">(
    "app-theme",
    "light"
  );
 
  return (
    <div>
      <p>Tema atual: {theme}</p>
      <button onClick={() => setTheme((t) => (t === "light" ? "dark" : "light"))}>
        Alternar Tema
      </button>
      <button onClick={removeTheme}>Redefinir para Padrão</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="Nome"
      />
      <input
        value={draft.email}
        onChange={(e) => setDraft((d) => ({ ...d, email: e.target.value }))}
        placeholder="Email"
      />
      <p>Rascunho salvo automaticamente no localStorage</p>
    </form>
  );
}

O que isso demonstra:

• Armazenamento com segurança de tipo usando o tipo de união "light" | "dark"
• Sintaxe da função atualizadora (prev) => next, assim como useState
• Armazenamento de objetos com serialização JSON
• Função remove para limpar a chave e redefinir o estado
• Abrir duas abas mostra a sincronização do tema através do evento storage

Análise Detalhada

Como Funciona

• Inicializador preguiçoso: O callback do useState lê do localStorage apenas na primeira renderização, evitando leituras redundantes a cada re-renderização.
• Proteção SSR: Todo acesso ao window é controlado por verificações typeof window === "undefined", então o hook retorna initialValue durante a renderização do lado do servidor sem inconsistência de hidratação.
• Ciclo completo JSON: Valores são serializados com JSON.stringify e desserializados com JSON.parse. Isso lida com tipos primitivos, arrays e objetos simples.
• Sincronização entre abas: O evento storage dispara em outras abas quando a mesma chave muda. O listener atualiza o estado local para corresponder.
• Atualizações funcionais: O setter aceita um valor direto ou uma função (prev) => next, espelhando a API do useState.

Parâmetros e Valores de Retorno

Variações

Com expiração: Adicione um TTL armazenando { value, expiresAt } e verificando na leitura:

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

Com serializador personalizado: Aceite opções serialize e deserialize para dados não-JSON (por exemplo, superjson para objetos Date, Map, Set).

Variante sessionStorage: Troque localStorage por sessionStorage - a API é idêntica, mas os dados são limpos quando a aba é fechada.

Notas TypeScript

• O genérico T flui de initialValue para o estado armazenado e o setter, permitindo inferência de tipo completa.
• Tipos de união como "light" | "dark" restringem a entrada do setter automaticamente.
• Para tipos complexos, passe o genérico explicitamente: useLocalStorage<User>("user", defaultUser).

Armadilhas

• Valores não serializáveis - Funções, Symbols, undefined e objetos circulares não sobrevivem ao JSON.stringify. Correção: Armazene apenas dados simples serializáveis. Use superjson para Date, Map, Set.
• Cota de armazenamento excedida - Navegadores limitam o localStorage a cerca de 5 MB. Correção: O try/catch no efeito de escrita lida silenciosamente com isso; considere avisar o usuário.
• O evento storage dispara apenas em outras abas - A mesma aba que escreveu o valor não recebe um evento storage. Correção: Este hook lida com atualizações na mesma aba via setState; a sincronização entre abas é tratada pelo listener de eventos.
• Colisões de chaves - Múltiplos aplicativos na mesma origem compartilham o localStorage. Correção: Prefira chaves com um namespace de aplicativo como myapp:theme.
• Inconsistência de hidratação - Se o servidor renderiza com initialValue mas o cliente lê um valor diferente do armazenamento, ocorre uma inconsistência. Correção: O inicializador preguiçoso é executado apenas no cliente. Para frameworks SSR, a renderização inicial usa initialValue, depois atualiza após a hidratação.

Alternativas

FAQs

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

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

Relacionados

• useToggle - combine com localStorage para toggles persistentes
• useMediaQuery - detecta a preferência de tema do sistema
• useState - o primitivo subjacente