useLayoutEffect en React: medir antes del pintado

useLayoutEffect es una versión de useEffect que se ejecuta antes: justo después de que React actualizó el DOM, pero antes de que el navegador pinte el nuevo frame. El código que contiene puede medir elementos y cambiar el layout, y el usuario solo ve el resultado final. Bloquea el pintado mientras se ejecuta, así que úsalo solo cuando necesites ese 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>;
}

Los efectos se declaran en el orden efecto, layout effect, pero la consola imprime primero el layout effect en cada renderizado. El orden de declaración no importa entre los dos hooks; importa su momento.

La sintaxis

La firma es idéntica a la de useEffect: una función de configuración, una limpieza opcional y un array de dependencias.

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

Todo lo que sabes sobre dependencias y limpieza de useEffect se aplica. La única diferencia es cuándo lo llama React.

Cuándo se ejecuta cada uno

Después de un renderizado, React actualiza el DOM y luego hace tres cosas en un orden fijo:

1. Ejecuta todas las limpiezas de los layout effects y los layout effects, de forma síncrona.
2. Deja que el navegador pinte. Si un layout effect cambió el estado, React primero vuelve a renderizar, todavía antes del pintado.
3. Ejecuta los efectos normales, normalmente después del pintado.

En todo el árbol, cada layout effect se ejecuta antes que cualquier efecto normal, y los hijos se ejecutan antes que sus padres, porque un padre solo puede terminar cuando sus hijos están en su 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>
    );
}

La consola muestra primero ambos layout effects, Child y luego Parent, y después ambos efectos normales en el mismo orden. El key={n} hace que cada clic monte un Parent nuevo, así que obtienes las mismas cuatro líneas cada vez. Agrega a cada efecto una limpieza que registre y mira cómo los viejos se ejecutan antes que los nuevos.

El problema del parpadeo

Imagina un tooltip que debe aparecer encima de su botón, a menos que no haya espacio arriba, en cuyo caso va debajo. No puedes saber si hay espacio hasta que el tooltip está en el DOM y puedes medir su altura. Así que el renderizado ocurre en dos pasadas:

1. Renderizar el tooltip en algún lugar, para poder medirlo.
2. Medirlo, calcular la posición real, cambiar el estado, renderizar otra vez.

Con useEffect, el navegador puede pintar entre esas pasadas, y el usuario ve el tooltip saltar de la primera posición a la segunda. Con useLayoutEffect, la segunda pasada ocurre antes del pintado, así que la primera posición nunca se muestra.

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

Pasa el cursor sobre el botón de arriba: no hay espacio encima, así que el tooltip aparece debajo. Pasa sobre el de abajo y aparece encima. La consola te dice qué lado eligió la medición. Cambia useLayoutEffect por useEffect y vuelve a pasar el cursor: ahora el tooltip puede aparecer un frame en la parte superior de la caja antes de moverse. En una máquina rápida suele ser demasiado rápido para notarlo, y justo por eso este error se publica y luego lo reportan desde teléfonos más lentos.

offsetHeight, offsetTop y getBoundingClientRect() obligan al navegador a calcular el layout, así que leerlos en el layout effect te da los valores reales del DOM que React acaba de escribir.

Medir un elemento

El mismo patrón sirve para cualquier tamaño del que dependa el renderizado: léelo con una ref en un layout effect, guárdalo en el estado y renderiza con él.

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

Haz clic en el botón y la línea del ancho se actualiza en el mismo frame que el texto. La página nunca muestra un texto nuevo junto a un ancho viejo, porque el segundo renderizado ocurre antes del pintado. Quita [text] del array de dependencias y la medición se ejecuta después de cada renderizado, incluido el que provoca su propio setWidth; se detiene ahí solo porque el ancho ya no cambia.

Prefiere useEffect

Un layout effect retiene el pintado hasta que termina, y si cambia el estado, hasta que también termina el renderizado extra. Uno lento hace que cada actualización de la página se sienta lenta. Usa useLayoutEffect solo cuando se cumple todo esto:

• El efecto lee el layout (tamaño, posición, scroll).
• Cambia lo que se renderiza según esa lectura.
• El estado intermedio sería visible y se vería mal.

Todo lo demás (obtener datos, suscripciones, temporizadores, registros, analítica) va en useEffect. Una regla rápida: empieza con useEffect y cambia solo si puedes ver un parpadeo.

useEffect normalmente se ejecuta después del pintado, pero no siempre. Cuando la actualización viene de una acción discreta del usuario, como un clic o una tecla, React puede ejecutar los efectos antes de que el navegador pinte. Esa es una de las razones por las que un parpadeo puede aparecer en una situación y no en otra.

Renderizado en el servidor

Los efectos nunca se ejecutan durante el renderizado en el servidor, y useLayoutEffect tampoco. El servidor envía el HTML del primer renderizado, y el layout effect se ejecuta solo después de la hidratación en el navegador. React 18 y anteriores advertían "useLayoutEffect does nothing on the server" cuando un componente así se renderizaba en el servidor; React 19 quitó esa advertencia.

Si el primer frame renderizado en el servidor se vería mal sin la medición, hay dos soluciones habituales: renderizar un fallback neutro (por ejemplo, ocultar el tooltip hasta medirlo), o renderizar el componente solo en el cliente:

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

useInsertionEffect

Hay un tercer hook de efectos, useInsertionEffect, que se ejecuta antes que cualquier layout effect. Existe para las librerías CSS-in-JS que generan etiquetas <style> en tiempo de ejecución: insertar los estilos ahí significa que un layout effect que mide un elemento ya lo ve con estilo. No puede actualizar el estado y las refs todavía no están conectadas, así que no sirve en el código de una aplicación. Si no estás escribiendo una librería de estilos, no lo vas a necesitar.