Conservar el tema y evitar el destello visual

Cuando se carga una página, React debe descargar, analizar y ejecutar JavaScript antes de poder leer localStorage y aplicar el tema correcto. Durante ese intervalo, el navegador renderiza la página con los estilos predeterminados. Si el usuario prefiere el modo oscuro pero el valor predeterminado es claro, verá un breve parpadeo blanco antes de que el tema se corrija.

La solución consiste en colocar un script en línea en la document head que se ejecute de forma síncrona antes que cualquier otro código. Este script lee localStorage inmediatamente y establece data-theme en document.documentElement. Como es un script bloqueante, el navegador aplica el atributo antes de pintar cualquier contenido.

Los scripts asíncronos o diferidos se ejecutan después de analizar el HTML y posiblemente después del primer pintado. Eso anula por completo el objetivo. El script en línea bloqueante no debe tener atributos async ni defer, y tampoco debe cargarse desde un archivo externo. El script debe ser muy pequeño para minimizar el coste de rendimiento.

El script bloqueante es mínimo: lea localStorage.getItem('theme'), compruebe window.matchMedia('(prefers-color-scheme: dark)').matches como alternativa y, después, llame a document.documentElement.setAttribute('data-theme', theme). Envuélvalo en un bloque try-catch por si localStorage no está disponible en la navegación privada.

En Next.js, utilice el componente Script de next/script con strategy="beforeInteractive" dentro de _document.js. La estrategia beforeInteractive inserta el script en el HTML de la página antes de que se ejecute cualquier JavaScript de la página, logrando el mismo comportamiento bloqueante en el proceso de compilación de Next.js.

En un proyecto de Vite o Create React App, edite index.html directamente y coloque la etiqueta de script en línea en el head, antes que cualquier otro script. Como index.html es el punto de entrada del navegador, el script se ejecuta antes de que React se inicie. Manténgalo conciso para que ocupe menos de 100 bytes.

En una aplicación renderizada en el servidor, este puede leer el tema de una cookie enviada con la solicitud. Después, el servidor establece data-theme en el HTML renderizado antes de enviarlo al navegador. Así se evita por completo cualquier parpadeo en el cliente, porque el tema correcto está presente desde el primer byte del HTML.

El flujo completo es el siguiente: el navegador descarga el HTML, el analizador encuentra el script en línea bloqueante, el script lee localStorage y establece data-theme, el analizador continúa, la página se pinta con el tema correcto y React se hidrata y recupera el mismo tema de localStorage. El usuario ve un único tema coherente desde el principio.

Para verificar que la solución funciona, abra las herramientas para desarrolladores de Chrome, vaya a la pestaña Network y limite la velocidad a Slow 3G. Vuelva a cargar la página. Si observa un cambio de tema durante la carga, el parpadeo no se ha solucionado. Con el script bloqueante instalado, el primer pintado ya debería mostrar el tema correcto incluso con conexiones lentas.

Si el estado inicial de React tiene light como valor predeterminado, pero el script bloqueante estableció dark antes de la hidratación, React puede mostrar una advertencia de discrepancia durante la hidratación. Evítelo inicializando también el estado del tema de React mediante la lectura de localStorage durante el renderizado inicial, para garantizar que el HTML renderizado por React coincida con el estado del DOM establecido por el script bloqueante.

Storybook y los entornos de prueba no cargan su index.html, por lo que el script bloqueante nunca se ejecuta. Proporcione un decorator o una configuración de pruebas que aplique un atributo data-theme predeterminado en esos entornos. Esto evita inconsistencias visuales confusas al desarrollar componentes de forma aislada.

¿Qué tipo de script debe utilizarse en la cabecera del documento para evitar el parpadeo del tema incorrecto?

Evite el parpadeo del tema incorrecto insertando un pequeño script en línea bloqueante en la cabecera del documento que lea localStorage y establezca data-theme antes de cualquier pintado. En Next.js, utilice strategy="beforeInteractive"; en Vite o CRA, añádalo directamente a index.html. Las aplicaciones SSR pueden leer una cookie para establecer el tema en el servidor.