Cuándo se ejecuta useLayoutEffect frente a useEffect

useLayoutEffect se ejecuta de forma síncrona inmediatamente después de que React haya aplicado las mutaciones del DOM, pero antes de que el navegador tenga la oportunidad de pintar esos cambios. Desde la perspectiva del navegador, el efecto de layout y las mutaciones del DOM forman parte del mismo bloque de trabajo síncrono e ininterrumpido.

useEffect se ejecuta de forma asíncrona después de que el navegador haya terminado de pintar. El usuario ve primero la interfaz actualizada y, a continuación, se ejecuta el efecto. Esto hace que useEffect interfiera menos con el rendimiento del renderizado, pero significa que cualquier cambio visible provocado por el efecto dará lugar a un segundo ciclo de pintado.

Puede verificar la diferencia de temporización registrando marcas de tiempo en ambos efectos: añada console.log('layout', Date.now()) en useLayoutEffect y console.log('passive', Date.now()) en useEffect. En la consola, la marca de tiempo del efecto de layout siempre será anterior a la del efecto pasivo, lo que confirma el orden de ejecución.

Si un useEffect actualiza un estado que afecta a la salida visual, el usuario ve dos renderizados: el renderizado inicial con el estado desactualizado y, después, el renderizado corregido cuando se ejecuta el efecto. Esto se manifiesta como un destello o un reajuste visible. useLayoutEffect lo evita porque sus actualizaciones de estado se aplican antes de que el navegador pinte nada.

Si llama a setState dentro de un useLayoutEffect, React ejecuta inmediatamente otro ciclo de renderizado y commit antes de pintar. El navegador solo pinta el resultado final: el usuario nunca ve el estado intermedio. Este es el caso de uso principal de useLayoutEffect: medir el DOM, calcular un nuevo valor, actualizar el estado y garantizar un único pintado limpio.

Como useLayoutEffect se ejecuta de forma síncrona antes del pintado y puede desencadenar renderizados adicionales, su uso excesivo puede perjudicar el rendimiento. Si el trabajo síncrono es pesado, bloquea el pintado del navegador y provoca tirones visibles. Úselo únicamente cuando necesite evitar un destello visual; para todo lo demás, use useEffect.

En React Strict Mode (solo durante el desarrollo), tanto useLayoutEffect como useEffect se invocan dos veces por montaje. La secuencia es: montaje, limpieza y nuevo montaje. Esto ayuda a detectar efectos que no realizan correctamente la limpieza. La doble invocación no ocurre en las compilaciones de producción.

La opción predeterminada siempre debe ser useEffect. Cambie a useLayoutEffect únicamente cuando pueda observar y reproducir un parpadeo visual o un problema de diseño incorrecto. El uso excesivo de useLayoutEffect bloquea innecesariamente la canalización de pintado del navegador y puede empeorar el rendimiento percibido.

useLayoutEffect no puede ejecutarse en el servidor porque en un entorno de servidor no hay DOM ni ciclo de pintado del navegador. Si se utiliza en un componente que se renderiza en el servidor, React emite una advertencia. La solución consiste en omitir condicionalmente el efecto: compruebe typeof window !== 'undefined' o cambie a useEffect para usar código compatible con SSR.

Pregúntese: «¿Este efecto cambia algo que el usuario verá en el primer pintado?». Si la respuesta es afirmativa, use useLayoutEffect para evitar un destello. Si no —por ejemplo, para obtener datos, suscripciones, analíticas, registros y la mayoría de los demás efectos secundarios—, use useEffect. Este marco de decisión cubre la mayoría de los casos reales.

useLayoutEffect se ejecuta en el mismo bloque síncrono que las mutaciones del DOM. React no puede procesar otro trabajo (como responder a eventos del usuario) mientras se ejecuta un useLayoutEffect. Por eso debe ser rápido y centrarse en una tarea concreta. El código síncrono de larga duración en useLayoutEffect retrasa directamente que el navegador muestre el contenido en pantalla.

¿Cuándo se ejecuta exactamente useLayoutEffect con respecto a las mutaciones del DOM y al pintado del navegador?

useLayoutEffect es síncrono y se ejecuta antes del pintado del navegador, por lo que resulta adecuado para medir el DOM y corregir aspectos visuales. useEffect se ejecuta después del pintado y es la opción adecuada para obtener datos, suscripciones y la mayoría de los efectos secundarios. Use useEffect como opción predeterminada y cambie a useLayoutEffect únicamente cuando un parpadeo visual confirme que es necesario. Evite usarlo en SSR sin las comprobaciones necesarias.