useLayoutEffect in React: misurare prima del disegno

useLayoutEffect è una versione di useEffect che viene eseguita prima: subito dopo che React ha aggiornato il DOM, ma prima che il browser disegni il nuovo frame. Il codice al suo interno può misurare elementi e cambiare il layout, e l'utente vede solo il risultato finale. Blocca il disegno mentre è in esecuzione, quindi usalo solo quando ti serve quel momento preciso.

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>;
}

Gli effetti sono dichiarati nell'ordine effect, layout effect, ma la console stampa per primo il layout effect a ogni rendering. Tra i due hook non conta l'ordine di dichiarazione; contano i loro tempi.

La sintassi

La firma è identica a quella di useEffect: una funzione di setup, una funzione di cleanup facoltativa e un array delle dipendenze.

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

Tutto ciò che sai su dipendenze e cleanup da useEffect vale anche qui. L'unica differenza è quando React lo chiama.

Quando viene eseguito ciascuno

Dopo un rendering, React aggiorna il DOM e poi fa tre cose in un ordine fisso:

1. Esegue tutte le funzioni di cleanup dei layout effect e i layout effect, in modo sincrono.
2. Lascia che il browser disegni la pagina. Se un layout effect ha impostato lo stato, React prima esegue un nuovo render, sempre prima del disegno.
3. Esegue gli effetti normali, di solito dopo il disegno.

In un albero, ogni layout effect viene eseguito prima di qualsiasi effetto normale, e i figli vengono eseguiti prima dei genitori, perché un genitore può terminare solo quando i suoi figli sono al loro posto:

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>
    );
}

La console mostra prima entrambi i layout effect, Child e poi Parent, poi entrambi gli effetti normali nello stesso ordine. Il key={n} fa sì che ogni clic monti un Parent nuovo, quindi ottieni ogni volta le stesse quattro righe. Aggiungi a ogni effetto una funzione di cleanup che registra un log e guarda quelle vecchie essere eseguite prima delle nuove.

Il problema dello sfarfallio

Immagina un tooltip che deve comparire sopra il suo pulsante, a meno che sopra non ci sia spazio, nel qual caso va sotto. Non puoi sapere se c'è spazio finché il tooltip non è nel DOM e puoi misurarne l'altezza. Quindi il rendering avviene in due passaggi:

1. Renderizza il tooltip da qualche parte, così da poterlo misurare.
2. Misuralo, calcola la posizione reale, imposta lo stato, renderizza di nuovo.

Con useEffect, il browser può disegnare la pagina tra quei due passaggi, e l'utente vede il tooltip saltare dalla prima posizione alla seconda. Con useLayoutEffect, il secondo passaggio avviene prima del disegno, quindi la prima posizione non viene mai mostrata.

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>
    );
}

Passa il mouse sul pulsante in alto: sopra non c'è spazio, quindi il tooltip compare sotto. Passa sopra quello in basso e compare sopra. La console ti dice quale lato ha scelto la misurazione. Cambia useLayoutEffect in useEffect e passa di nuovo il mouse: ora il tooltip può lampeggiare in cima al riquadro per un frame prima di spostarsi. Su una macchina veloce spesso è troppo rapido per notarlo, ed è proprio per questo che questo bug arriva in produzione e poi viene segnalato da telefoni più lenti.

offsetHeight, offsetTop e getBoundingClientRect() costringono tutti il browser a calcolare il layout, quindi leggerli nel layout effect ti dà i valori reali del DOM che React ha appena scritto.

Misurare un elemento

Lo stesso schema funziona per qualsiasi dimensione da cui dipende il rendering: leggila con un ref in un layout effect, salvala nello stato, renderizza con essa.

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>
    );
}

Clicca il pulsante e la riga della larghezza si aggiorna nello stesso frame del testo. La pagina non mostra mai un testo nuovo accanto a una larghezza vecchia, perché il secondo rendering avviene prima del disegno. Togli [text] dall'array delle dipendenze e la misurazione viene eseguita dopo ogni rendering, compreso quello provocato dal suo stesso setWidth; si ferma lì solo perché la larghezza non cambia più.

Preferisci useEffect

Un layout effect ritarda il disegno finché non restituisce, e se imposta lo stato, anche finché non termina il rendering in più. Uno lento fa sembrare lento ogni aggiornamento della pagina. Usa useLayoutEffect solo quando sono vere tutte queste condizioni:

• L'effetto legge il layout (dimensione, posizione, scorrimento).
• Cambia ciò che viene renderizzato in base a quella lettura.
• Lo stato intermedio sarebbe visibile e apparirebbe sbagliato.

Tutto il resto (recupero dei dati, sottoscrizioni, timer, log, analytics) va in useEffect. Una regola veloce: parti con useEffect, e passa all'altro solo se vedi uno sfarfallio.

Di solito useEffect viene eseguito dopo il disegno, ma non sempre. Quando l'aggiornamento arriva da un'azione discreta dell'utente come un clic o la pressione di un tasto, React può eseguire gli effetti prima che il browser disegni la pagina. È uno dei motivi per cui uno sfarfallio può comparire in una situazione e non in un'altra.

Rendering lato server

Gli effetti non vengono mai eseguiti durante il rendering lato server, e nemmeno useLayoutEffect. Il server invia l'HTML del primo rendering, e il layout effect viene eseguito solo dopo l'hydration nel browser. React 18 e le versioni precedenti avvisavano con "useLayoutEffect does nothing on the server" quando un componente del genere veniva renderizzato sul server; React 19 ha eliminato quell'avviso.

Se il primo frame renderizzato dal server apparirebbe sbagliato senza la misurazione, ci sono due soluzioni comuni: renderizzare un fallback neutro (per esempio, nascondere il tooltip finché non viene misurato), oppure renderizzare il componente solo sul client:

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

useInsertionEffect

Esiste un terzo hook per gli effetti, useInsertionEffect, che viene eseguito prima di qualsiasi layout effect. Esiste per le librerie CSS in JS che generano tag <style> a runtime: inserire lì gli stili significa che un layout effect che misura un elemento lo vede già con il suo stile. Non può aggiornare lo stato e i ref non sono ancora collegati, quindi non serve a nulla nel codice applicativo. Se non stai scrivendo una libreria di stili, non ti servirà.