Evitando sobrecarga de layout e tremulação visual

A instabilidade da disposição ocorre quando o JavaScript alterna entre ler propriedades do DOM e escrever no DOM dentro de um loop. Cada leitura depois de uma escrita força o navegador a recalcular a disposição de forma síncrona para retornar um valor preciso. Isso pode transformar o que deveria ser um único cálculo de disposição em dezenas deles, prejudicando gravemente o desempenho.

React agrupa todas as chamadas de setState dentro de manipuladores de eventos e efeitos em uma única nova renderização. Esse agrupamento natural impede o padrão leitura-escrita-leitura que causa instabilidade dentro de um único ciclo de renderização. No React 18, o agrupamento também se estende a funções de retorno assíncronas e promessas, reduzindo a instabilidade da disposição causada por atualizações concorrentes de estado.

A cintilação ocorre quando um useEffect lê o DOM, atualiza o estado, dispara uma nova renderização e o navegador pinta duas vezes: uma com o estado inicial e outra com o estado corrigido. A primeira pintura aparece brevemente antes de ser substituída. Isso é mais visível em efeitos que ajustam propriedades do leiaute, como altura, largura ou posição.

Abra o Chrome DevTools, acesse a aba Renderização (pelo menu de três pontos em Mais ferramentas) e ative "Intermitência de pintura". As áreas repintadas são destacadas em verde. Se você vir um componente cintilar na primeira renderização e depois ser repintado imediatamente com um leiaute diferente, isso confirma uma dupla pintura causada por uma atualização de estado conduzida por useEffect.

Mova as leituras do DOM e as atualizações de estado resultantes de useEffect para useLayoutEffect. A mesma medição e atualização de estado agora acontecem de forma síncrona antes da pintura; o React renderiza novamente e confirma as alterações no mesmo bloco, e o navegador pinta apenas o estado final e correto. A intermitência verde no DevTools desaparece.

O padrão sem cintilação é: ler o DOM em useLayoutEffect, chamar setState com a medição, fazer o React renderizar novamente de forma síncrona, confirmar o DOM corrigido e deixar o navegador pintar uma vez com o resultado final. Esse é o padrão consagrado para posicionar dicas de ferramenta, calcular deslocamentos de cabeçalhos fixos e configurar animações.

A grande maioria dos efeitos deve ficar em useEffect: busca de dados (a cintilação durante o carregamento é aceitável e esperada), assinaturas de eventos ou fluxos, registro de eventos e análise, temporizadores e qualquer efeito que não afete imediatamente o leiaute visível. Usar useLayoutEffect em excesso quando useEffect resolveria é um antipadrão que prejudica o desempenho.

Reserve useLayoutEffect para medições do DOM que alimentam a saída visual: posições de dicas de ferramenta, lógica baseada no tamanho dos elementos, restauração da posição de rolagem e configuração de animações que lê as dimensões iniciais. Um sinal claro de que você deve fazer a troca é observar um clarão visível, de um único quadro, de um leiaute incorreto na primeira renderização.

Os dois ganchos têm assinaturas idênticas: useLayoutEffect(callback, deps) e useEffect(callback, deps). A única diferença é o momento em que a função de retorno de chamada é executada. Você pode alternar entre eles com uma alteração de uma palavra no código. Comece com useEffect e só mude para useLayoutEffect se confirmar a ocorrência de cintilação.

É válido e comum usar os dois ganchos no mesmo componente para responsabilidades diferentes. Por exemplo, um componente de gráfico pode usar useLayoutEffect para medir a largura do contêiner e definir o viewBox do SVG de forma síncrona, e depois usar useEffect para buscar os dados do gráfico de forma assíncrona. Cada gancho cuida do aspecto em que o momento de execução é importante.

Além da intermitência de pintura do DevTools, você pode adicionar um contador no console dentro do componente para contar as renderizações. Se um componente registrar "render" duas vezes na primeira montagem — uma vez com o estado inicial e outra com a medição corrigida —, você terá um cenário de dupla pintura. Mover a medição para useLayoutEffect deve reduzir isso a uma única renderização registrada após a montagem (sem contar a duplicação em Strict Mode).

A instabilidade do leiaute é causada pela alternância entre leituras e escritas no DOM. O processamento em lotes do React evita a maior parte disso durante as renderizações. A cintilação acontece quando useEffect mede o DOM e atualiza o estado, causando duas pinturas. Corrija a cintilação movendo as medições do DOM para useLayoutEffect. Use useEffect por padrão para todo o resto: busca de dados, assinaturas, registro de eventos e temporizadores.