Détecter le thème de couleurs du système

La requête média CSS prefers-color-scheme détecte si l’utilisateur a configuré son système d’exploitation pour utiliser un thème de couleurs sombre ou clair. Elle accepte deux valeurs : dark et light. Cette préférence est définie au niveau de l’OS dans les paramètres système, et non dans le navigateur.

Vous pouvez appliquer des styles sombres uniquement en CSS avec @media (prefers-color-scheme: dark) { ... }. Dans ce bloc, remplacez les couleurs, arrière-plans et bordures pour les adapter à une palette sombre. Cette approche ne nécessite aucun JavaScript et fonctionne même avant le montage de React.

En JavaScript, window.matchMedia('(prefers-color-scheme: dark)') renvoie un objet MediaQueryList. Vous pouvez l’utiliser pour lire par programmation la préférence système actuelle dans des hooks React ou des gestionnaires d’événements. Cela fait le lien entre les requêtes média CSS et votre logique JS.

L’objet MediaQueryList possède une propriété matches qui renvoie une valeur booléenne. Si matches vaut true, le système est en mode sombre ; si false, il est en mode clair. Vous lisez généralement cette valeur une seule fois lors du montage pour initialiser l’état de votre thème.

Les utilisateurs peuvent modifier leur schéma de couleurs OS à tout moment. Pour réagir dynamiquement, appelez mediaQuery.addEventListener('change', handler), où handler reçoit l’élément MediaQueryListEvent mis à jour. L’objet événement possède également une valeur booléenne matches qui reflète la nouvelle préférence.

Une approche claire consiste à créer un hook personnalisé avec useSyncExternalStore. Le hook s’abonne à mediaQuery.addEventListener et fournit une fonction qui renvoie l’instantané mediaQuery.matches. Cela maintient le hook synchronisé avec l’API externe du navigateur sans gestion manuelle de l’état.

Lorsque votre composant est démonté, vous devez supprimer l’écouteur d’événement pour éviter les fuites de mémoire. Dans le nettoyage de useEffect, appelez mediaQuery.removeEventListener('change', handler). Avec useSyncExternalStore, la fonction d’abonnement doit renvoyer une fonction de désabonnement qui fait de même.

La préférence système correspond à ce que l’OS signale. Cependant, les utilisateurs souhaitent souvent remplacer indépendamment le thème de l’application, par exemple pour conserver l’application en mode clair alors que l’OS est en mode sombre. Votre architecture doit distinguer la valeur système par défaut d’une surcharge utilisateur explicite stockée dans localStorage.

Chrome DevTools vous permet d’émuler les préférences de schéma de couleurs sans modifier les paramètres de votre OS. Ouvrez DevTools, accédez à l’onglet Rendu et recherchez la liste déroulante « Émuler la fonctionnalité de média CSS prefers-color-scheme ». Cette fonction est très utile pour tester rapidement les deux thèmes pendant le développement.

Une bonne implémentation du mode sombre lit la préférence système comme point de départ par défaut et l’applique immédiatement. Cela respecte le paramètre d’accessibilité de l’utilisateur. Ce n’est qu’après que l’utilisateur a explicitement changé le thème dans votre application que vous devez stocker et utiliser une autre surcharge.

Sur le serveur, window.matchMedia n’existe pas. Si vous effectuez un rendu côté serveur, vérifiez typeof window !== 'undefined' avant d’appeler cette API. Pour les applications SSR, lisez plutôt la préférence utilisateur depuis un cookie ou un en-tête HTTP afin d’éviter les incohérences d’hydratation.

Quelle propriété d’un objet MediaQueryList indique si la requête média correspond actuellement ?

La requête média prefers-color-scheme expose la préférence de couleurs de l’OS en CSS comme en JavaScript. Utilisez window.matchMedia pour lire les changements et les écouter, nettoyez toujours les écouteurs d’événements et distinguez les valeurs système par défaut des surcharges utilisateur. L’émulation dans Chrome DevTools accélère le test des deux thèmes.