useLayoutEffect no React: Sincronia Pré-Repaint
⚡ Curso de React.js • Web-ZoneWare

useLayoutEffect: Sincronização Antes do Repaint da Tela e Prevenção de Flickering Visual

Lição 24 de 50

useLayoutEffect: Sincronização Antes do Repaint da Tela e Prevenção de Flickering Visual

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:

  1. 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.
  2. 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 o useEffect é 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:

  1. O Tooltip precisa saber onde o botão que o acionou está posicionado na tela para calcular suas propriedades top e left via getBoundingClientRect().
  2. 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: 0 ou opacidade total).
    • O navegador pinta o Tooltip no canto superior da tela.
    • O useEffect roda, lê a posição do botão, recalcula o estado para top: 250px, left: 400px e dispara um re-render.
    • O navegador pinta novamente o Tooltip na posição correta.
  3. 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:

  1. O React muta o DOM e coloca o Tooltip no DOM.
  2. Antes que a tela seja pintada, o useLayoutEffect executa de forma síncrona.
  3. Ele lê getBoundingClientRect() do botão âncora e invoca imediatamente o setCoords().
  4. 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).
  5. 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:

CODE 84 linhas
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:

CODE 1 linha
Warning: useLayoutEffect does nothing on the server, because its effect cannot be encoded into the server renderer&#039;s output format.

Para contornar essa advertência de forma elegante em bibliotecas isomórficas, utiliza-se o padrão corporativo useIsomorphicLayoutEffect:

JavaScript 5 linhas
import { useLayoutEffect, useEffect } from 'react';
 
// Seleciona useLayoutEffect no navegador e useEffect seguro no servidor Node.js
export const useIsomorphicLayoutEffect =
  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima