Detectar el esquema de colores del sistema

La consulta de medios CSS prefers-color-scheme detecta si el usuario ha configurado su sistema operativo para usar un tema de color oscuro o claro. Acepta dos valores: dark y light. Esta preferencia se establece en el nivel del sistema operativo, en la configuración del sistema, no en el navegador.

Puede aplicar estilos oscuros exclusivamente con CSS mediante @media (prefers-color-scheme: dark) { ... }. Dentro de este bloque, sobrescriba los colores, fondos y bordes para adaptarlos a una paleta oscura. Este enfoque no requiere JavaScript y funciona incluso antes de que React se monte.

En JavaScript, window.matchMedia('(prefers-color-scheme: dark)') devuelve un objeto MediaQueryList. Puede usarlo para leer mediante programación la preferencia actual del sistema dentro de hooks de React o controladores de eventos. Este es el puente entre las consultas de medios CSS y la lógica de JS.

El objeto MediaQueryList tiene una propiedad matches que devuelve un booleano. Si matches es true, el sistema está en modo oscuro; si es false, está en modo claro. Normalmente se lee una vez durante el montaje para inicializar el estado del tema.

Los usuarios pueden cambiar el esquema de color de su sistema operativo en cualquier momento. Para responder dinámicamente, llame a mediaQuery.addEventListener('change', handler), donde handler recibe el MediaQueryListEvent actualizado. El objeto de evento también tiene un booleano matches que refleja la nueva preferencia.

Un enfoque limpio consiste en crear un hook personalizado mediante useSyncExternalStore. El hook se suscribe a mediaQuery.addEventListener y proporciona una función de snapshot que devuelve mediaQuery.matches. Así, el hook se mantiene sincronizado con la API externa del navegador sin gestionar el estado manualmente.

Cuando el componente se desmonta, debe eliminar el detector de eventos para evitar fugas de memoria. En la limpieza de un useEffect, llame a mediaQuery.removeEventListener('change', handler). Con useSyncExternalStore, la función de suscripción debe devolver una función para cancelar la suscripción que haga lo mismo.

La preferencia del sistema es la que informa el sistema operativo. Sin embargo, los usuarios suelen querer anular el tema de la aplicación de forma independiente; por ejemplo, mantener la aplicación en modo claro mientras el sistema operativo está en modo oscuro. Su arquitectura debe distinguir entre el valor predeterminado del sistema y una anulación explícita del usuario almacenada en localStorage.

Chrome DevTools permite emular las preferencias de esquema de color sin cambiar la configuración del sistema operativo. Abra DevTools, vaya a la pestaña Rendering y busque el menú desplegable «Emular la función de medios CSS prefers-color-scheme». Esto resulta muy útil para probar rápidamente ambos temas durante el desarrollo.

Una buena implementación del modo oscuro lee la preferencia del sistema como punto de partida predeterminado y la aplica de inmediato. Esto demuestra respeto por la configuración de accesibilidad del usuario. Solo después de que el usuario cambie explícitamente el tema en la aplicación debe almacenar y usar una anulación diferente.

En el servidor, window.matchMedia no existe. Si renderiza en el servidor, compruebe typeof window !== 'undefined' antes de llamar a matchMedia. En las aplicaciones con SSR, lea la preferencia del usuario de una cookie o una cabecera HTTP para evitar discrepancias de hidratación.

¿Qué propiedad de un objeto MediaQueryList indica si la consulta de medios coincide actualmente?

La consulta de medios prefers-color-scheme expone la preferencia de color del sistema operativo tanto en CSS como en JavaScript. Use window.matchMedia para leer los cambios y escuchar sus actualizaciones, elimine siempre los detectores de eventos y distinga entre los valores predeterminados del sistema y las anulaciones del usuario. La emulación de Chrome DevTools acelera las pruebas de ambos temas.