¿Cómo evito el parpadeo del tema equivocado en Next.js?

Resuelve el tema en un script síncrono dentro del head del documento, antes de que se parsee el body. Lee localStorage y prefers-color-scheme y pone data-theme en el elemento html. Un useEffect no sirve: se ejecuta después de que React monte, es decir, después del primer pintado, cuando la paleta equivocada ya está en pantalla.

¿Para qué sirve la propiedad CSS color-scheme?

Le dice al navegador qué paleta usar en la interfaz que pinta él mismo: scrollbars, controles de formulario, subrayado del corrector y el color por defecto del lienzo. Sin ella, una página oscura mantiene scrollbars y selects claros. Ligala al tema que estás renderizando de verdad, no a prefers-color-scheme, o el toggle y la interfaz del navegador acabarán diciendo cosas distintas.

¿Conviene usar light-dark() en vez de variables por tema?

light-dark() quita un nivel de indirección: escribes los dos valores en una sola declaración en lugar de redefinir la variable en dos bloques. Es Baseline desde mayo de 2024 y depende de que color-scheme esté puesto. Encaja bien en un proyecto nuevo; sobre un set de tokens ya existente con decenas de variables, la reescritura rara vez se paga sola.

¿Por qué prefers-color-scheme solo funciona si cambio el ajuste del sistema?

Porque el código registra el listener de cambio pero nunca lee mediaQuery.matches al montar. addEventListener solo dispara cuando la preferencia cambia durante la sesión, así que quien ya tenía el modo oscuro activado se queda con la paleta clara hasta que toca el ajuste del sistema. Hay que leer matches una vez dentro del efecto.

Buscar

Tema oscuro en Next.js sin parpadeo del tema equivocado

Xabier Lameiro · 3 feb 2023

Respuesta rápida

Un tema oscuro en Next.js necesita tres cosas, y las variables CSS son solo la primera:

Definir la paleta por tema — un bloque [data-theme='dark'], otro [data-theme='light'], con los tokens redefinidos en cada uno.
Resolver el tema antes del primer pintado — un <script> síncrono pequeño en _document que lee localStorage y prefers-color-scheme y pone data-theme en <html>. Un useEffect llega tarde: la paleta equivocada ya está en pantalla.
Poner color-scheme — si no, los scrollbars, los <select> y el lienzo por defecto se quedan claros sobre una página oscura.

La parte que casi todos los tutoriales hacen mal (el mío incluido, durante tres años) es la segunda. Registrar un listener de change en matchMedia no es lo mismo que leer la preferencia: el listener solo dispara si el visitante cambia el tema del sistema con la pestaña ya abierta.

Lo que publiqué, y por qué nunca funcionó

La versión original de este post describía exactamente lo que corría esta web: variables CSS, data-theme="light" a fuego en _document, y un hook suscrito a prefers-color-scheme. Tenía dos defectos que se tapaban el uno al otro lo bastante bien como para que no lo viera en tres años.

El primero está en el hook. Llamaba a mediaQuery.addEventListener('change', handler) y nada más — nunca leía mediaQuery.matches. change dispara cuando la preferencia cambia, no cuando te suscribes, así que quien tenía el modo oscuro activado antes de abrir la página se llevaba la paleta clara y se quedaba con ella. La única manera de ver el tema oscuro era cambiar el ajuste del sistema con la pestaña ya abierta, que es exactamente lo que yo hacía cada vez que lo "probaba".

El segundo es peor. El hook lo montaba una sola página — el diálogo de ajustes —, así que en el resto de rutas data-theme nunca se movía del "light" escrito en _document. La paleta oscura no es que fuera difícil de alcanzar: es que no se renderizaba nunca. Cuando por fin la apliqué a todo el sitio, una superficie de ventana que llevaba ahí desde 2023 resultó estar pintando blanco sobre blanco, porque usaba un token --white-color independiente del tema que nadie había visto jamás en oscuro.

Mientras tanto, en globals.css había esto:

globals.css

@media (prefers-color-scheme: dark) {
    html {
        color-scheme: dark;
    }
}

Esa regla lee el sistema operativo directamente, mientras que la paleta de la página venía de data-theme. Sobre Next.js 15.5, en agosto de 2026 y con el sistema en oscuro, la página reportaba data-theme="light" y color-scheme: dark a la vez: fondo claro, tokens de texto claros y scrollbars oscuros, porque al navegador se le había dicho que la página era oscura y el CSS decía lo contrario.

1 — Variables CSS por tema

Esta parte del post original estaba bien y no ha cambiado. Los colores viven como tripletas de canales para poder reutilizarlos con alfa, y cada tema los redefine:

globals.css

:root {
    /* independientes del tema */
    --white-color: 255, 255, 255;
    --blue-color: 29, 88, 154;
}
[data-theme='dark'] {
    color-scheme: dark;
    --blog-background: 30, 30, 30;
    --blog-font: 223, 222, 223;
    --blog-border: 107, 107, 107;
}
[data-theme='light'] {
    color-scheme: light;
    --blog-background: 255, 255, 255;
    --blog-font: 39, 39, 39;
    --blog-border: 118, 118, 118;
}

La trampa está en el bloque :root. Lo que se quede ahí es independiente del tema por definición, y un token como --white-color usado como color de superficie seguirá siendo blanco bajo [data-theme='dark']. Si un valor nombra un color en vez de un rol, no pinta nada en un componente con tema.

2 — color-scheme, la propiedad que arregla la interfaz del propio navegador

color-scheme es lo que le dice al navegador qué paleta usar para las partes de la página que pinta él: scrollbars, checkboxes, radios, desplegables <select>, el subrayado del corrector ortográfico y el color del lienzo por defecto antes de que cargue tu CSS. Es Baseline —disponible en todos los motores— desde enero de 2022, y falta en la mayoría de tutoriales de tema oscuro, incluida la primera versión de este.

Dos detalles importan más que la propiedad en sí:

Decláralo dentro de los bloques [data-theme], no en una media query. Una media query sigue al sistema operativo. Tu paleta sigue al tema aplicado, que después de un toggle no es lo mismo. Ligados al mismo selector, no pueden separarse.

También arregla el color del flash previo al pintado. Con color-scheme: dark, el navegador pinta su lienzo por defecto en oscuro en vez de en blanco, así que hasta el fotograma anterior a tu hoja de estilos tiene el color correcto.

3 — Resolver el tema antes del primer pintado

El servidor no puede conocer la preferencia del visitante —no existe cabecera de petición para prefers-color-scheme—, así que el HTML tiene que salir con un valor por defecto y corregirse en el navegador. La corrección tiene que ocurrir antes de que se pinte el body, lo que descarta useEffect.

Un script síncrono en el head lo consigue. Bloquea el parser, que normalmente es algo a evitar, pero aquí son cuatro bytes y es justo el objetivo:

_document.tsx

const themeBootstrap = `(function(){try{var s=localStorage.getItem('theme');var t=s==='dark'||s==='light'?s:matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.setAttribute('data-theme',t)}catch(e){}})()`;
const Document = (props: Props) => (
    <Html lang={props.__NEXT_DATA__.locale} data-theme="light">
        <Head>
            <meta charSet="utf-8" />
            <script dangerouslySetInnerHTML={{ __html: themeBootstrap }} />
            {/* ...el resto del head */}
        </Head>
        <body>
            <Main />
            <NextScript />
        </body>
    </Html>
);

Apuntes sobre los detalles, porque cada uno está por un motivo:

data-theme="light" se queda en el marcado. Es el fallback para quien tenga JavaScript desactivado, y el script lo sobrescribe antes de pintar nada.
El valor guardado se comprueba primero, para que la elección explícita gane al sistema. Un toggle que el siguiente cambio del sistema deshace en silencio no es un toggle.
try/catch alrededor de localStorage. En modo privado y con ciertas extensiones, leerlo lanza. Sin la protección, el script entero muere y todo el mundo se queda en claro.
Va en _document, no en _app. _document se renderiza solo en servidor y nunca se hidrata, así que mutar documentElement desde ahí no provoca ningún error de hidratación.

Meterlo en el head es además lo que lo hace independiente de tu árbol de componentes. Ese fue el fallo real en mi caso: el tema lo aplicaba un hook que solo montaba una página. En el head se ejecuta en todas las rutas, sin importar qué se renderice.

4 — El hook: leer el valor inicial y guardar la elección

El hook sigue haciendo falta —para el toggle, y para seguir al sistema mientras la pestaña está abierta—, pero tiene que leer matches al montar en vez de esperar a un evento change:

useDarkMode.ts

export const THEME_STORAGE_KEY = 'theme';
const useDarkMode = () => {
    const [theme, setTheme] = React.useState<null | 'dark' | 'light'>(null);
    React.useEffect(() => {
        if (typeof window === 'undefined' || !window.matchMedia) return undefined;
        const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
        let stored: string | null = null;
        try {
            stored = window.localStorage.getItem(THEME_STORAGE_KEY);
        } catch {
            // Almacenamiento bloqueado (modo privado, extensiones). Caemos a la preferencia del sistema.
        }
        // La línea que le faltaba a la versión original de este post.
        if (stored === 'dark' || stored === 'light') setTheme(stored);
        else setTheme(mediaQuery.matches ? 'dark' : 'light');
        // Seguir al sistema solo mientras el visitante no haya elegido por su cuenta.
        const handler = (event: MediaQueryListEvent) => {
            let hasExplicitChoice = false;
            try {
                hasExplicitChoice = window.localStorage.getItem(THEME_STORAGE_KEY) !== null;
            } catch {
                hasExplicitChoice = false;
            }
            if (!hasExplicitChoice) setTheme(event.matches ? 'dark' : 'light');
        };
        mediaQuery.addEventListener('change', handler);
        return () => mediaQuery.removeEventListener('change', handler);
    }, []);
    React.useEffect(() => {
        if (typeof window !== 'undefined' && theme) {
            document.documentElement.setAttribute('data-theme', theme);
        }
    }, [theme]);
    const toggleTheme = React.useCallback(() => {
        setTheme((current) => {
            const next = current === 'dark' ? 'light' : 'dark';
            try {
                window.localStorage.setItem(THEME_STORAGE_KEY, next);
            } catch {
                // La elección sigue aplicando a esta vista de página.
            }
            return next;
        });
    }, []);
    return { theme, toggleTheme };
};

El handler de change no hace nada a propósito una vez hay una elección guardada. Sin esa comprobación, a quien eligió claro se le daría la vuelta la próxima vez que su portátil pasara a modo noche — el toggle parecería roto en lugar de sobrescrito.

toggleTheme usa la forma funcional de setTheme en vez de leer theme del closure, así no necesita theme en su lista de dependencias y no puede actuar sobre un valor obsoleto.

5 — Conectar el toggle

A estas alturas no queda nada especial. El componente lee el tema actual para su etiqueta y llama a toggleTheme:

settings.tsx

const { theme, toggleTheme } = useDarkMode();
return (
    <IconWithName
        icon="/settings/theme.png"
        alt=""
        name={f({ id: theme === 'dark' ? 'settings.dark' : 'settings.light' })}
        onClick={toggleTheme}
        pressed={theme === 'dark'}
    />
);

theme es null en el primer render — el valor solo se resuelve dentro del efecto, porque leer localStorage o matchMedia durante el render haría que el marcado del servidor y el del cliente no coincidieran y saldría un error de hidratación. Si necesitas que el texto sea correcto también en el HTML del servidor, etiqueta el control desde el data-theme del documento.

light-dark(), y si compensa

light-dark() mete los dos valores en una sola declaración y elige entre ellos según el esquema de color en uso del elemento:

light-dark.css

:root {
    color-scheme: light dark;
    --blog-background: light-dark(#ffffff, #1e1e1e);
    --blog-font: light-dark(#272727, #dfdedf);
}

Es Baseline desde mayo de 2024, así que hoy es usable con fallback, y quita una molestia real: la estructura de dos bloques donde cada token hay que declararlo dos veces en dos sitios alejados, y añadir uno implica acordarse de añadirlo en ambos.

No he migrado esta web a ello, y el motivo no es el soporte de navegadores. light-dark() se resuelve contra color-scheme, así que solo cubre el par claro/oscuro — en cuanto quieras un tercer tema, o una sobreescritura por sección, vuelves a redefinir variables bajo un selector. Con un set de tokens ya partido en dos bloques, la reescritura compra CSS más limpio y nada que el visitante pueda ver. En un proyecto nuevo empezaría por ahí.

La pega que nadie menciona: theme-color

<meta name="theme-color"> colorea el cromo del navegador en móvil, y acepta un atributo media:

theme-color.html

<meta name="theme-color" content="#FFFFFF" media="(prefers-color-scheme: light)" />
<meta name="theme-color" content="#1E1E1E" media="(prefers-color-scheme: dark)" />

Ese atributo media lee el sistema operativo, y un elemento <meta> no puede leer localStorage. Así que quien sobrescriba el tema tendrá la página en una paleta y el cromo del navegador en la otra. Cambiar el atributo content desde el handler del toggle es la única forma de mantenerlos sincronizados, y conviene decidir si te importa antes de escribir ese código.

Cómo comprobar que funciona de verdad

Tres comprobaciones, en la consola del navegador, con el sistema en oscuro:

console.js

// 1. El bootstrap se ejecutó y coincide con el sistema.
document.documentElement.getAttribute('data-theme'); // "dark"
// 2. La interfaz del propio navegador sigue el mismo tema.
getComputedStyle(document.documentElement).colorScheme; // "dark"
// 3. La elección explícita gana al sistema, y sobrevive a un recargado.
localStorage.setItem('theme', 'light');
location.reload();
// -> data-theme "light", colorScheme "light"

La segunda es la que destapó el fallo de esta web: data-theme decía light mientras colorScheme decía dark. Si esas dos alguna vez no coinciden, la paleta y la interfaz del navegador están leyendo fuentes distintas.

Todo el código en mi repositorio de github, si te gusta este proyecto, o si el contenido te ha ayudado de alguna manera puedes recompensarme con una ⭐️, ¡Gracias!