useLayoutEffect: Sincronização Antes do Repaint da Tela e Prevenção de Flickering Visual
📑 Índice do Conteúdo
O Ciclo de Renderização e a Fase de Pintura (Paint)
Para entender verdadeiramente o papel do hook useLayoutEffect, precisamos descer ao nível de como o React e os motores dos navegadores modernos (Blink, Gecko, WebKit) cooperam para desenhar elementos visuais na tela.
O ciclo de vida de renderização de um componente React é dividido em duas fases primordiais:
- Fase de Render (Render Phase): O React invoca a função do componente, calcula o novo Virtual DOM e gera a árvore de alterações necessárias (diffing). Esta fase é pura e não possui efeitos colaterais visíveis.
- Fase de Commit (Commit Phase): O React aplica as mutações diretamente aos nós reais da árvore do DOM do navegador (inserindo, removendo ou atualizando nós).
Aqui ocorre uma bifurcação temporal sutil, mas de imenso impacto visual:
- Imediatamente após o React mutar o DOM, o navegador já possui a nova estrutura de nós na memória, mas ainda não executou a pintura visual (Paint) dos pixels no monitor.
- O hook
useLayoutEffecté executado exatamente nessa brecha: de forma síncrona, logo após a mutação do DOM, mas rigorosamente ANTES de o navegador pintar a tela. - Por outro lado, o hook padrão
useEffecté adiado: o navegador primeiro pinta a tela para que o usuário veja a interface sem atraso, e somente depois do Paint ouseEffecté executado de forma assíncrona.
Analogia dos Bastidores do Teatro: Imagine uma peça de teatro. O useLayoutEffect é o contra-regra que entra no palco enquanto as cortinas ainda estão fechadas para ajustar a posição de uma cadeira antes que a luz acenda. O useEffect é o bilheteiro que avisa a produção que novos ingressos foram vendidos depois que a cena já começou com a luz acesa.
O Problema do Flickering Visual (Layout Shift)
Por que essa diferença de milissegundos importa tanto na experiência do usuário? A resposta está em componentes que precisam ler dimensões do DOM (como largura, altura ou coordenadas de rolagem) para então calcular estilos de posicionamento.
Considere um componente de Tooltip (dica de contexto) ou Popover:
- O Tooltip precisa saber onde o botão que o acionou está posicionado na tela para calcular suas propriedades
topeleftviagetBoundingClientRect(). - Se você calcular essa posição dentro de um
useEffect:- O React insere o Tooltip no DOM na posição inicial (ex:
top: 0, left: 0ou opacidade total). - O navegador pinta o Tooltip no canto superior da tela.
- O
useEffectroda, lê a posição do botão, recalcula o estado paratop: 250px, left: 400pxe dispara um re-render. - O navegador pinta novamente o Tooltip na posição correta.
- O React insere o Tooltip no DOM na posição inicial (ex:
- O Resultado Indesejado: O usuário enxerga um salto visual abrupto (um flash ou “flickering”) do Tooltip pulando de uma coordenada para outra em uma fração de segundo, prejudicando o acabamento profissional da aplicação.
Como o useLayoutEffect Elimina o Flickering
Ao substituir useEffect por useLayoutEffect para medições geométricas de nós do DOM, o fluxo é totalmente sanado:
- O React muta o DOM e coloca o Tooltip no DOM.
- Antes que a tela seja pintada, o
useLayoutEffectexecuta de forma síncrona. - Ele lê
getBoundingClientRect()do botão âncora e invoca imediatamente osetCoords(). - O React percebe a atualização síncrona de estado e recalcula a renderização antes de liberar a thread para o navegador executar a pintura (Paint).
- Quando o monitor finalmente pinta os pixels na tela, o Tooltip já surge perfeitamente posicionado nas coordenadas finais, sem nenhum piscar ou deslocamento perceptível!
Comparativo Definitivo: useEffect vs useLayoutEffect
| Critério de Comparação | useEffect (Padrão) |
useLayoutEffect (Especializado) |
|---|---|---|
| Momento de Execução | Assíncrono, após o navegador pintar a tela (Post-Paint). | Síncrono, após mutação do DOM e antes da pintura (Pre-Paint). |
| Bloqueio de Interface | Não bloqueia a renderização visual da tela. | Bloqueia a pintura da tela até que o callback termine. |
| Impacto em Performance | Excelente; mantém a rolagem e animações fluidas a 60/120 FPS. | Pode causar engasgos (jank) se executar lógicas pesadas. |
| Casos de Uso Primários | Fetch de APIs, timers, subscrições de eventos e WebSockets. | Medição geométrica (getBoundingClientRect), cálculo de tooltips, animações de layout. |
| Comportamento em SSR | Executa normalmente no cliente após hidratação. | Emite aviso de aviso no servidor (não tem acesso ao DOM). |
A Regra dos 98%: Em 98% dos casos práticos de desenvolvimento de software em React, você deve utilizar useEffect. Use useLayoutEffect unicamente quando a medição síncrona de layout for estritamente necessária para evitar glitches e tremores visuais perceptíveis pelo usuário.
Exemplo Prático: Posicionamento Perfeito de Tooltip sem Flickering
Veja no exemplo abaixo a implementação corporativa de um Tooltip que mede dinamicamente o elemento âncora antes da pintura visual:
import React, { useState, useRef, useLayoutEffect } from 'react';
// Componente de Tooltip Dinâmico com Sincronia Pré-Repaint
export function SafeTooltip({ targetRef, text, isOpen }) {
const tooltipRef = useRef(null);
const [coords, setCoords] = useState({ top: 0, left: 0 });
useLayoutEffect(() => {
// Executa síncronamente antes do Paint do navegador
if (!isOpen || !targetRef.current || !tooltipRef.current) return;
const targetRect = targetRef.current.getBoundingClientRect();
const tooltipRect = tooltipRef.current.getBoundingClientRect();
// Posiciona centralizado acima do botão alvo
const calculatedTop = targetRect.top - tooltipRect.height - 8;
const calculatedLeft = targetRect.left + (targetRect.width / 2) - (tooltipRect.width / 2);
setCoords({
top: calculatedTop,
left: Math.max(8, calculatedLeft) // Impede vazar para fora da margem esquerda
});
}, [isOpen, targetRef]);
if (!isOpen) return null;
return (
<div
ref={tooltipRef}
style={{
position: 'fixed',
top: `${coords.top}px`,
left: `${coords.left}px`,
backgroundColor: '#0f172a',
color: '#f8fafc',
padding: '6px 12px',
borderRadius: '6px',
fontSize: '13px',
fontWeight: '500',
boxShadow: '0 10px 15px -3px rgba(0, 0, 0, 0.3)',
zIndex: 9999,
pointerEvents: 'none'
}}
>
{text}
</div>
);
}
// Componente Principal de Demonstração
export default function TooltipDemo() {
const buttonRef = useRef(null);
const [showTooltip, setShowTooltip] = useState(false);
return (
<div style={{ padding: '40px', textAlign: 'center' }}>
<h3>Demonstração do useLayoutEffect</h3>
<p>Passe o mouse sobre o botão para inspecionar o posicionamento instantâneo:</p>
<button
ref={buttonRef}
onMouseEnter={() => setShowTooltip(true)}
onMouseLeave={() => setShowTooltip(false)}
style={{
padding: '12px 24px',
backgroundColor: '#3b82f6',
color: '#ffffff',
border: 'none',
borderRadius: '8px',
cursor: 'pointer',
fontWeight: '600'
}}
>
Botão de Ação Alvo
</button>
<SafeTooltip
targetRef={buttonRef}
text="Posicionamento síncrono e perfeito pré-repaint!"
isOpen={showTooltip}
/>
</div>
);
}
useLayoutEffect e Server-Side Rendering (SSR)
Em ambientes com renderização do lado do servidor (como Next.js, Remix ou Gatsby), nem o useEffect nem o useLayoutEffect executam durante o HTML inicial gerado no Node.js. No entanto, o React emitirá um alerta explícito no console ao encontrar useLayoutEffect no servidor:
Warning: useLayoutEffect does nothing on the server, because its effect cannot be encoded into the server renderer039;s output format.
Para contornar essa advertência de forma elegante em bibliotecas isomórficas, utiliza-se o padrão corporativo useIsomorphicLayoutEffect:
import { useLayoutEffect, useEffect } from 'react';
// Seleciona useLayoutEffect no navegador e useEffect seguro no servidor Node.js
export const useIsomorphicLayoutEffect =
typeof window !== 'undefined' ? useLayoutEffect : useEffect;
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE