Medindo elementos do DOM com useLayoutEffect

element.getBoundingClientRect() retorna um objeto DOMRect com o tamanho e a posição do elemento em relação à área visível: top, right, bottom, left, width e height. Para retornar valores precisos, ele força o navegador a calcular a disposição dos elementos, portanto chame-o com moderação.

Se você ler getBoundingClientRect() em um useEffect, o navegador já terá pintado a tela. Se você então atualizar o estado com base nessa medição, React renderizará novamente e o navegador pintará outra vez. Os usuários poderão ver o elemento brevemente na posição ou com o tamanho incorreto antes que a correção apareça na segunda pintura.

A leitura das medidas em useLayoutEffect ocorre depois das mutações do DOM, mas antes da pintura. Qualquer atualização de estado provocada pela medição fará React renderizar novamente de forma síncrona e confirmar o DOM corrigido — tudo antes que o navegador pinte qualquer coisa. O usuário verá somente o resultado final e correto em um único ciclo de pintura.

Uma dica de ferramenta precisa aparecer perto do elemento que a aciona. Meça a posição desse elemento em useLayoutEffect usando getBoundingClientRect(), calcule a posição absoluta da dica de ferramenta e armazene essa posição no estado. A dica de ferramenta será renderizada no local correto já na primeira pintura, sem um salto visível a partir de uma posição inicial incorreta.

Para animar um elemento de seu tamanho natural, sem restrições, até um tamanho fixo, você precisa conhecer o tamanho natural antes de aplicar a restrição. Leia a altura do elemento em useLayoutEffect antes que qualquer estilo de animação seja aplicado, armazene-a no estado e use-a como valor do quadro-chave inicial para sua transição do CSS.

Quando uma página tem um cabeçalho fixo, o conteúdo da página precisa de um preenchimento superior igual à altura do cabeçalho para não ficar oculto atrás dele. Meça a altura do cabeçalho em useLayoutEffect usando uma referência: headerRef.current.getBoundingClientRect().height. Defina esse valor como paddingTop no contêiner de conteúdo. A disposição estará correta desde a primeira renderização.

Quando você chama setState dentro de useLayoutEffect, React executa imediatamente outro ciclo de renderização e confirmação no mesmo bloco síncrono. Essa nova renderização também executa seu useLayoutEffect. Tenha cuidado para não criar um loop infinito: atualize o estado somente se a nova medição for diferente do valor atual do estado.

No servidor, os elementos do DOM não existem, portanto getBoundingClientRect() causaria um erro ou retornaria zeros. Proteja seu useLayoutEffect com uma verificação: if (typeof window === 'undefined') return;. Em aplicações com SSR, talvez seja necessário hidratar a aplicação com um tamanho de espaço reservado e medir depois da hidratação no cliente.

Uma medição única com useLayoutEffect fornece o tamanho no momento da montagem. Para acompanhar mudanças de tamanho conforme o elemento é redimensionado, devido ao redimensionamento da janela, ao conteúdo dinâmico ou a alterações no CSS, use ResizeObserver. Ele executa uma função de retorno sempre que o tamanho do elemento muda, sendo mais adequado para componentes responsivos.

Se vários efeitos precisarem da mesma medição, calcule-a uma vez e compartilhe-a por meio de um contexto ou passando-a como propriedades. Calcular o mesmo valor de getBoundingClientRect() em várias chamadas de useLayoutEffect dispara várias leituras síncronas da disposição, cada uma relativamente custosa. Sempre que possível, agrupe as medições.

As referências são preenchidas antes da execução dos efeitos. Quando useLayoutEffect é executado, há garantia de que ref.current aponta para o elemento do DOM. É por isso que o padrão funciona: useLayoutEffect(() => { const rect = ref.current.getBoundingClientRect(); ... }, []). A referência nunca é nula dentro de um efeito de disposição em um componente montado.

Por que é melhor chamar getBoundingClientRect() em useLayoutEffect do que em useEffect?

Use getBoundingClientRect() em useLayoutEffect para ler as medidas do DOM depois das mutações, mas antes da pintura. As atualizações de estado provenientes dessas medições causam uma nova renderização síncrona incluída na mesma pintura, evitando cintilações. Proteja-se contra SSR com uma verificação de typeof window. Para acompanhar o tamanho continuamente, prefira ResizeObserver.