useLayoutEffect no React: medir antes de o navegador pintar

useLayoutEffect é uma versão do useEffect que executa mais cedo: logo depois que o React atualizou o DOM, mas antes de o navegador pintar o novo frame. O código dentro dele pode medir elementos e mudar o layout, e o usuário só vê o resultado final. Ele bloqueia a pintura enquanto executa, então use-o só quando precisar desse momento.

import { useState, useEffect, useLayoutEffect } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    console.log('1. render');

    useEffect(() => {
        console.log('3. effect (usually after paint)');
    });

    useLayoutEffect(() => {
        console.log('2. layout effect (before paint)');
    });

    return <button onClick={() => setCount(count + 1)}>Rendered with {count}</button>;
}

Os efeitos são declarados na ordem efeito, layout effect, mas o console imprime o layout effect primeiro em toda renderização. A ordem de declaração não importa entre os dois hooks; o momento de cada um, sim.

A sintaxe

A assinatura é idêntica à do useEffect: uma função de setup, uma limpeza opcional e um array de dependências.

useLayoutEffect(() => {
    // runs after the DOM update, before paint
    return () => {
        // cleanup, before the next run and on unmount
    };
}, [dependencies]);

Tudo o que você sabe sobre dependências e limpeza do useEffect vale aqui. A única diferença é quando o React o chama.

Quando cada um executa

Depois de uma renderização, o React atualiza o DOM e então faz três coisas em uma ordem fixa:

1. Executa todas as limpezas de layout effects e os layout effects, de forma síncrona.
2. Deixa o navegador pintar a tela. Se um layout effect definiu estado, o React primeiro renderiza de novo, ainda antes da pintura.
3. Executa os efeitos comuns, normalmente depois da pintura.

Em uma árvore, todo layout effect executa antes de qualquer efeito comum, e os filhos executam antes dos pais, já que um pai só pode terminar quando os filhos estão no lugar:

import { useEffect, useLayoutEffect, useState } from 'react';

function Child() {
    useLayoutEffect(() => {
        console.log('Child layout effect');
    });
    useEffect(() => {
        console.log('Child effect');
    });
    return <p>Child</p>;
}

function Parent() {
    useLayoutEffect(() => {
        console.log('Parent layout effect');
    });
    useEffect(() => {
        console.log('Parent effect');
    });
    return <Child />;
}

export default function App() {
    const [n, setN] = useState(0);
    return (
        <div>
            <button onClick={() => setN(n + 1)}>Render again ({n})</button>
            <Parent key={n} />
        </div>
    );
}

O console mostra primeiro os dois layout effects, Child e depois Parent, e em seguida os dois efeitos comuns na mesma ordem. A key={n} faz cada clique montar um Parent novo, então você recebe as mesmas quatro linhas toda vez. Adicione uma limpeza que registre algo em cada efeito e veja os antigos executarem antes dos novos.

O problema da piscada

Imagine um tooltip que deve aparecer acima do botão, a menos que não haja espaço acima, caso em que ele vai para baixo. Você não consegue saber se há espaço até o tooltip estar no DOM e você poder medir a altura dele. Então a renderização acontece em duas passadas:

1. Renderizar o tooltip em algum lugar, para que possa ser medido.
2. Medi-lo, calcular a posição real, definir o estado e renderizar de novo.

Com useEffect, o navegador pode pintar a tela entre essas passadas, e o usuário vê o tooltip pular da primeira posição para a segunda. Com useLayoutEffect, a segunda passada acontece antes da pintura, então a primeira posição nunca é mostrada.

import { useLayoutEffect, useRef, useState } from 'react';

function Tooltip({ anchor, text }) {
    const ref = useRef(null);
    const [top, setTop] = useState(0);

    useLayoutEffect(() => {
        const height = ref.current.offsetHeight;
        const above = anchor.offsetTop - height - 6;
        const fits = above >= 0;
        console.log(fits ? 'room above: placing above' : 'no room above: placing below');
        setTop(fits ? above : anchor.offsetTop + anchor.offsetHeight + 6);
    }, [anchor]);

    const style = {
        position: 'absolute', top, left: anchor.offsetLeft,
        background: '#222', color: '#fff', padding: '4px 8px', borderRadius: 4, fontSize: 13,
    };
    return <div ref={ref} style={style}>{text}</div>;
}

export default function App() {
    const [anchor, setAnchor] = useState(null);
    const show = (e) => setAnchor(e.currentTarget);
    const hide = () => setAnchor(null);

    return (
        <div style={{ position: 'relative', height: 160 }}>
            <button onMouseEnter={show} onMouseLeave={hide} style={{ position: 'absolute', top: 0 }}>
                Hover me (top)
            </button>
            <button onMouseEnter={show} onMouseLeave={hide} style={{ position: 'absolute', top: 110 }}>
                Hover me (lower)
            </button>
            {anchor && <Tooltip anchor={anchor} text="A tooltip that picks its side" />}
        </div>
    );
}

Passe o mouse sobre o botão de cima: não há espaço acima dele, então o tooltip aparece embaixo. Passe sobre o de baixo e ele aparece acima. O console diz qual lado a medição escolheu. Troque useLayoutEffect por useEffect e passe o mouse de novo: agora o tooltip pode piscar no topo da caixa por um frame antes de se mover. Em uma máquina rápida muitas vezes é rápido demais para perceber, e é exatamente por isso que esse bug vai para produção e depois é relatado por quem usa celulares mais lentos.

offsetHeight, offsetTop e getBoundingClientRect() forçam o navegador a calcular o layout, então lê-los no layout effect dá os valores reais do DOM que o React acabou de escrever.

Medindo um elemento

O mesmo padrão funciona para qualquer tamanho de que a renderização dependa: leia-o com uma ref em um layout effect, guarde-o no estado e renderize com ele.

import { useLayoutEffect, useRef, useState } from 'react';

export default function App() {
    const [text, setText] = useState('Short');
    const [width, setWidth] = useState(null);
    const boxRef = useRef(null);

    useLayoutEffect(() => {
        const w = Math.round(boxRef.current.getBoundingClientRect().width);
        console.log('measured width for', JSON.stringify(text));
        setWidth(w);
    }, [text]);

    return (
        <div>
            <button onClick={() => setText(text + ' and longer')}>Make it longer</button>
            <p>
                <span ref={boxRef} style={{ background: '#ffeaa7', padding: '2px 6px' }}>
                    {text}
                </span>
            </p>
            <p>The highlighted text is {width} px wide.</p>
        </div>
    );
}

Clique no botão e a linha da largura atualiza no mesmo frame que o texto. A página nunca mostra um texto novo ao lado de uma largura antiga, porque a segunda renderização acontece antes da pintura. Remova [text] do array de dependências e a medição executa depois de toda renderização, inclusive a que o próprio setWidth causa; ela só para ali porque a largura não muda mais.

Prefira o useEffect

Um layout effect segura a pintura até retornar e, se define estado, até a renderização extra terminar também. Um layout effect lento faz toda atualização da página parecer lenta. Use useLayoutEffect só quando tudo isto for verdade:

• O efeito lê o layout (tamanho, posição, rolagem).
• Ele muda o que é renderizado com base nessa leitura.
• O estado intermediário ficaria visível e pareceria errado.

Todo o resto (busca de dados, assinaturas, timers, logs, analytics) fica no useEffect. Uma regra rápida: comece com useEffect e só troque se conseguir ver uma piscada.

O useEffect normalmente executa depois da pintura, mas nem sempre. Quando a atualização vem de uma ação pontual do usuário, como um clique ou uma tecla, o React pode executar os efeitos antes de o navegador pintar a tela. Esse é um dos motivos pelos quais uma piscada pode aparecer em uma situação e não em outra.

Renderização no servidor

Os efeitos nunca executam durante a renderização no servidor, e o useLayoutEffect também não. O servidor envia o HTML da primeira renderização, e o layout effect só executa depois da hidratação no navegador. O React 18 e versões anteriores avisavam "useLayoutEffect does nothing on the server" quando um componente assim era renderizado no servidor; o React 19 removeu esse aviso.

Se o primeiro frame renderizado no servidor ficaria errado sem a medição, há duas correções comuns: renderizar um fallback neutro (por exemplo, esconder o tooltip até ele ser medido) ou renderizar o componente só no cliente:

function ClientOnly({ children }) {
    const [mounted, setMounted] = useState(false);
    useEffect(() => setMounted(true), []);
    return mounted ? children : null;
}

useInsertionEffect

Existe um terceiro hook de efeito, o useInsertionEffect, que executa antes de qualquer layout effect. Ele existe para bibliotecas de CSS-in-JS que geram tags <style> em tempo de execução: inserir os estilos ali significa que um layout effect que mede um elemento já o vê estilizado. Ele não pode atualizar estado e as refs ainda não estão conectadas, então não tem utilidade em código de aplicação. Se você não está escrevendo uma biblioteca de estilos, não vai precisar dele.