Quando useLayoutEffect é executado em comparação com useEffect

useLayoutEffect é executado de forma síncrona imediatamente depois que React aplica as mutações ao DOM, mas antes que o navegador tenha a oportunidade de pintar essas alterações. Do ponto de vista do navegador, o efeito de disposição e as mutações do DOM fazem parte do mesmo bloco ininterrupto de trabalho síncrono.

useEffect é executado de forma assíncrona depois que o navegador conclui a pintura. O usuário vê primeiro a interface atualizada e, em seguida, o efeito é executado. Isso torna useEffect menos perturbador para o desempenho da renderização, mas significa que qualquer alteração visível causada pelo efeito resultará em um segundo ciclo de pintura.

Você pode verificar a diferença de temporização registrando marcas de tempo nos dois efeitos: adicione console.log('layout', Date.now()) em useLayoutEffect e console.log('passive', Date.now()) em useEffect. No console, a marca de tempo do efeito de disposição será sempre anterior à marca de tempo do efeito passivo, confirmando a ordem de execução.

Se um useEffect atualizar o estado que afeta a saída visual, o usuário verá duas renderizações: a renderização inicial com o estado desatualizado e, depois, a renderização corrigida quando o efeito for executado. Isso se manifesta como uma piscada visível ou uma reorganização da disposição dos elementos. useLayoutEffect evita esse problema porque suas atualizações de estado são confirmadas antes que o navegador pinte qualquer coisa.

Se você chamar setState dentro de um useLayoutEffect, React executará imediatamente outro ciclo de renderização e confirmação antes da pintura. O navegador pintará apenas o resultado final — o usuário nunca verá o estado intermediário. Esse é o principal caso de uso de useLayoutEffect: medir o DOM, calcular um novo valor, atualizar o estado e garantir uma única pintura limpa.

Como useLayoutEffect é executado de forma síncrona antes da pintura e pode disparar renderizações adicionais, seu uso excessivo pode prejudicar o desempenho. Se o trabalho síncrono for pesado, ele impedirá a pintura do navegador, causando travamentos visíveis. Use-o somente quando precisar evitar uma alteração visual momentânea; use useEffect em todos os outros casos.

No modo estrito do React, somente durante o desenvolvimento, tanto useLayoutEffect quanto useEffect são invocados duas vezes a cada montagem. A sequência é: montar, limpar e montar novamente. Isso ajuda a detectar efeitos que não realizam a limpeza corretamente. A dupla invocação não ocorre nas compilações de produção.

A escolha padrão deve ser sempre useEffect. Só altere para useLayoutEffect quando você puder observar e reproduzir uma cintilação visual ou um problema de disposição incorreta. O uso excessivo de useLayoutEffect bloqueia desnecessariamente o fluxo de pintura do navegador e pode reduzir o desempenho percebido.

useLayoutEffect não pode ser executado no servidor porque não há DOM nem ciclo de pintura do navegador em um ambiente de servidor. Se for usado em um componente renderizado no servidor, React emitirá um aviso. A solução é ignorar o efeito condicionalmente: verifique typeof window !== 'undefined' ou mude para useEffect em código compatível com SSR.

Pergunte a si mesmo: "Esse efeito altera algo que o usuário verá já na primeira pintura?" Se sim, use useLayoutEffect para evitar uma piscada. Se não — para buscar dados, assinaturas, análise de dados, registro e a maioria dos outros efeitos colaterais — use useEffect. Essa estrutura de decisão abrange a maioria dos casos do mundo real.

useLayoutEffect é executado no mesmo bloco síncrono que as mutações do DOM. React não pode processar outro trabalho, como responder a eventos do usuário, enquanto um useLayoutEffect está sendo executado. Por isso, ele precisa ser rápido e concentrado. Um código síncrono de longa duração em useLayoutEffect atrasa diretamente a renderização do navegador na tela.

Em que momento exatamente useLayoutEffect é executado em relação às mutações do DOM e à pintura do navegador?

useLayoutEffect é síncrono e é executado antes da pintura do navegador, sendo adequado para medir o DOM e fazer correções visuais. useEffect é executado depois da pintura e é a escolha certa para buscar dados, assinaturas e a maioria dos efeitos colaterais. Use useEffect como padrão e só mude quando uma cintilação visual confirmar que useLayoutEffect é necessário. Evite-o em SSR sem proteções.