Rilevare lo schema colori del sistema

La media query CSS prefers-color-scheme rileva se l'utente ha configurato il sistema operativo per utilizzare un tema con colori scuri o chiari. Accetta due valori: dark e light. Questa preferenza viene impostata a livello di sistema nelle impostazioni del sistema operativo, non nel browser.

È possibile applicare gli stili scuri esclusivamente in CSS utilizzando @media (prefers-color-scheme: dark) { ... }. All'interno di questo blocco, sovrascrivere colori, sfondi e bordi per adattarli a una palette scura. Questo approccio non richiede JavaScript e funziona anche prima del montaggio di React.

In JavaScript, window.matchMedia('(prefers-color-scheme: dark)') restituisce un oggetto MediaQueryList. È possibile utilizzarlo per leggere programmaticamente la preferenza di sistema corrente all'interno degli hook di React o dei gestori di eventi. È il collegamento tra le media query CSS e la logica JavaScript.

L'oggetto MediaQueryList dispone di una proprietà matches che restituisce un valore booleano. Se matches è true, il sistema è in modalità scura; se è false, è in modalità chiara. In genere si legge questa proprietà una volta al montaggio per inizializzare lo stato del tema.

Gli utenti possono modificare in qualsiasi momento lo schema di colori del sistema operativo. Per rispondere dinamicamente, chiamare mediaQuery.addEventListener('change', handler), dove handler riceve l'oggetto MediaQueryListEvent aggiornato. Anche l'oggetto dell'evento dispone di un valore booleano matches che riflette la nuova preferenza.

Un approccio efficace consiste nel creare un hook personalizzato utilizzando useSyncExternalStore. L'hook si sottoscrive a mediaQuery.addEventListener e fornisce una funzione snapshot che restituisce mediaQuery.matches. In questo modo l'hook rimane sincronizzato con l'API esterna del browser senza dover gestire manualmente lo stato.

Quando il componente viene smontato, è necessario rimuovere il listener dell'evento per evitare perdite di memoria. Nella funzione di pulizia di un useEffect, chiamare mediaQuery.removeEventListener('change', handler). Con useSyncExternalStore, la funzione subscribe deve restituire una funzione di annullamento della sottoscrizione che esegua la stessa operazione.

La preferenza di sistema è quella comunicata dal sistema operativo. Tuttavia, spesso gli utenti desiderano sovrascrivere indipendentemente il tema dell'app, ad esempio mantenendo l'app in modalità chiara mentre il sistema operativo è in modalità scura. L'architettura dovrebbe distinguere tra il valore predefinito di sistema e un override esplicito dell'utente memorizzato in localStorage.

Chrome DevTools consente di emulare le preferenze dello schema di colori senza modificare le impostazioni del sistema operativo. Aprire DevTools, accedere alla scheda Rendering e individuare il menu a discesa "Emulate CSS media feature prefers-color-scheme". È uno strumento prezioso per testare rapidamente entrambi i temi durante lo sviluppo.

Una buona implementazione della modalità scura legge la preferenza di sistema come punto di partenza predefinito e la applica immediatamente. In questo modo si rispetta l'impostazione di accessibilità scelta dall'utente. Solo dopo che l'utente ha cambiato esplicitamente il tema nell'app si dovrebbe memorizzare e utilizzare un override diverso.

Sul server, window.matchMedia non esiste. Se si esegue il rendering sul server, verificare typeof window !== 'undefined' prima di chiamare matchMedia. Nelle app SSR, leggere invece la preferenza dell'utente da un cookie o da un'intestazione HTTP per evitare incongruenze durante l'hydration.

Quale proprietà di un oggetto MediaQueryList indica se la media query corrisponde attualmente?

La media query prefers-color-scheme espone la preferenza di colori del sistema operativo sia in CSS sia in JavaScript. Utilizzare window.matchMedia per leggere le modifiche e ascoltarle, rimuovere sempre i listener degli eventi e distinguere i valori predefiniti di sistema dagli override dell'utente. L'emulazione in Chrome DevTools accelera i test di entrambi i temi.