Hook useEffect

Sincronize um componente com um sistema externo executando efeitos colaterais após a renderização.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Executa após cada renderização
useEffect(() => {
  console.log("renderizado");
});
 
// Executa uma vez ao montar
useEffect(() => {
  fetchData();
}, []);
 
// Executa quando as dependências mudam
useEffect(() => {
  document.title = `Você clicou ${count} vezes`;
}, [count]);
 
// Limpeza ao desmontar ou antes de reexecutar
useEffect(() => {
  const id = setInterval(tick, 1000);
  return () => clearInterval(id);
}, []);

Quando usar isso: Você precisa sincronizar com algo fora do React - buscar dados, assinar eventos, manipular o DOM ou configurar timers.

Exemplo Funcional

"use client";
 
import { useEffect, useState } from "react";
 
export function WindowSize() {
  const [size, setSize] = useState({ width: 0, height: 0 });
 
  useEffect(() => {
    function handleResize() {
      setSize({ width: window.innerWidth, height: window.innerHeight });
    }
 
    handleResize(); // Define o tamanho inicial
    window.addEventListener("resize", handleResize);
 
    return () => window.removeEventListener("resize", handleResize);
  }, []);
 
  return (
    <p className="text-sm font-mono">
      Janela: {size.width} × {size.height}
    </p>
  );
}

O que isso demonstra:

• Assinando um evento do navegador (resize) dentro do useEffect
• Retornando uma função de limpeza para remover o listener ao desmontar
• Array de dependências vazio [] para que o efeito seja executado apenas uma vez ao montar
• Definindo o estado inicial dentro do efeito para evitar incompatibilidade de hidratação SSR

Imersão Profunda

Como Funciona

• useEffect executa após o navegador pintar a tela, não durante a renderização.
• O React chama sua função de configuração após o componente montar e após cada re-renderização onde as dependências mudaram.
• Antes de reexecutar o efeito, o React chama a função de limpeza anterior (se fornecida).
• Ao desmontar, o React chama a função de limpeza uma última vez.
• No Strict Mode durante o desenvolvimento, o React monta, desmonta e remonta cada componente para expor a lógica de limpeza ausente.

Parâmetros e Valores de Retorno

Variações

Busca de dados com limpeza (controlador de abortar):

useEffect(() => {
  const controller = new AbortController();
 
  async function load() {
    const res = await fetch(`/api/users/${id}`, {
      signal: controller.signal,
    });
    const data = await res.json();
    setUser(data);
  }
 
  load();
  return () => controller.abort();
}, [id]);

Conectando a um WebSocket:

useEffect(() => {
  const ws = new WebSocket(url);
  ws.onmessage = (e) => setMessages((prev) => [...prev, JSON.parse(e.data)]);
  return () => ws.close();
}, [url]);

Sincronizando com localStorage:

useEffect(() => {
  localStorage.setItem("theme", theme);
}, [theme]);

Notas TypeScript

// Efeito com async - deve envolver porque useEffect não pode retornar uma Promise
useEffect(() => {
  async function fetchData() {
    const res = await fetch("/api/data");
    const json: DataType = await res.json();
    setData(json);
  }
  fetchData();
}, []);
 
// TypeScript detecta automaticamente tipos de retorno de limpeza ausentes

Armadilhas

• Loop infinito - Atualizar um estado que também é uma dependência faz com que o efeito seja executado indefinidamente. Correção: Restrinja seu array de dependências ou mova a atualização do estado para trás de uma condição.

• Dependências ausentes - Omitir um valor do array de dependências causa dados obsoletos dentro do efeito. Correção: Inclua todos os valores reativos usados dentro do efeito, ou refatore para remover a dependência.

• Async diretamente em useEffect - Retornar uma Promise em vez de uma função de limpeza produz um aviso do React. Correção: Defina uma função async dentro do efeito e chame-a imediatamente.

• Condições de corrida em re-renderizações rápidas - Se id mudar rapidamente, um fetch mais antigo pode resolver após um mais novo e sobrescrever dados corretos. Correção: Use um AbortController ou um flag booleano ignore na limpeza.

• Executando no servidor - useEffect não executa durante SSR. Acessar window ou document sem proteção causa erros de build. Correção: Acesse APIs do navegador apenas dentro do useEffect ou atrás de uma verificação typeof window !== "undefined".

Alternativas

Por que não buscar em useEffect? Para muitos aplicativos, frameworks como Next.js oferecem busca de dados no lado do servidor que evita spinners de carregamento e waterfalls. Reserve a busca do useEffect para necessidades de dados puramente do lado do cliente.

Exemplo do Mundo Real

De uma aplicação SaaS de produção Next.js 15 / React 19 (SystemsArchitect.io).

// Exemplo de produção: Navegação por teclado para cartões de estudo
// Arquivo: src/hooks/use-card-keyboard.ts
import { useEffect } from "react";
 
interface UseCardKeyboardOptions {
  isAutoplayOn: boolean;
  cardNumber: number;
  totalCards: number;
  hasMoreCards: boolean;
  onCardClick: () => void;
  onNext: () => void;
  onPrev: () => void;
}
 
export function useCardKeyboard({
  isAutoplayOn, cardNumber, totalCards, hasMoreCards,
  onCardClick, onNext, onPrev,
}: UseCardKeyboardOptions) {
  useEffect(() => {
    const handleKeyDown = (event: KeyboardEvent) => {
      if (isAutoplayOn) return;
      if (event.code === "Space" || event.key === " ") {
        event.preventDefault();
        onCardClick();
      } else if (event.key === "ArrowLeft" || event.key === "a") {
        event.preventDefault();
        if (cardNumber > 1) onPrev();
      } else if (event.key === "ArrowRight" || event.key === "d") {
        event.preventDefault();
        if (cardNumber < totalCards || hasMoreCards) onNext();
      }
    };
    window.addEventListener("keydown", handleKeyDown);
    return () => window.removeEventListener("keydown", handleKeyDown);
  }, [cardNumber, totalCards, hasMoreCards, isAutoplayOn, onCardClick, onNext, onPrev]);
}

O que isso demonstra em produção:

• A limpeza remove o listener de keydown ao desmontar e sempre que as dependências mudam, evitando o acúmulo de manipuladores obsoletos.
• Todo valor referenciado dentro do efeito é incluído no array de dependências. Faltar até mesmo um (como cardNumber) causaria bugs de closure obsoleta onde valores antigos são capturados.
• As callbacks onCardClick, onNext e onPrev devem ser envolvidas em useCallback pelo componente pai. Sem isso, cada re-renderização do pai cria novas referências de função, fazendo com que este efeito desinscreva e reinscreva o listener desnecessariamente.
• A guarda isAutoplayOn no topo do manipulador é um padrão de produção para desabilitar a entrada do teclado durante a reprodução automática sem remover o listener completamente.
• Extrair isso para um hook customizado mantém o componente limpo e torna o comportamento do teclado testável independentemente.

FAQs

useEffect(() => {
  async function fetchData() {
    const res = await fetch("/api/data");
    setData(await res.json());
  }
  fetchData();
}, []);

useEffect(() => {
  const controller = new AbortController();
  fetch(`/api/users/${id}`, { signal: controller.signal })
    .then(res => res.json())
    .then(setUser);
  return () => controller.abort();
}, [id]);

useEffect((): (() => void) => {
  const id = setInterval(tick, 1000);
  return () => clearInterval(id);
}, []);
// TypeScript infere o tipo de limpeza automaticamente
// na maioria dos casos - tipagem explícita raramente é necessária.

Relacionados

• useState - estado que seus efeitos leem e escrevem
• useRef - valores mutáveis que persistem entre renderizações sem disparar efeitos
• useCallback - estabiliza funções usadas como dependências de efeito
• Hooks Customizados - extrai lógica de efeito reutilizável em hooks customizados