Detecting System Color Scheme

The prefers-color-scheme CSS media query detects whether the user has configured their operating system to use a dark or light color theme. It accepts two values: dark and light. This preference is set at the OS level in system settings, not in the browser.

You can apply dark styles purely in CSS using @media (prefers-color-scheme: dark) { ... }. Inside this block, you override colors, backgrounds, and borders to suit a dark palette. This approach requires no JavaScript and works even before React mounts.

In JavaScript, window.matchMedia('(prefers-color-scheme: dark)') returns a MediaQueryList object. You can use this to read the current system preference programmatically inside React hooks or event handlers. This is the bridge between CSS media queries and your JS logic.

The MediaQueryList object has a matches property that returns a boolean. If matches is true, the system is in dark mode; if false, it is in light mode. You typically read this once on mount to initialize your theme state.

Users can change their OS color scheme at any time. To respond dynamically, call mediaQuery.addEventListener('change', handler) where handler receives the updated MediaQueryListEvent. The event object also has a matches boolean reflecting the new preference.

A clean approach is to build a custom hook using useSyncExternalStore. The hook subscribes to mediaQuery.addEventListener and provides a snapshot function that returns mediaQuery.matches. This keeps the hook in sync with the external browser API without manual state management.

When your component unmounts, you must remove the event listener to avoid memory leaks. In a useEffect cleanup, call mediaQuery.removeEventListener('change', handler). With useSyncExternalStore, the subscribe function must return an unsubscribe function that does the same.

The system preference is what the OS reports. But users often want to override the app theme independently, for example keeping the app light while the OS is in dark mode. Your architecture should distinguish between the system default and an explicit user override stored in localStorage.

Chrome DevTools lets you emulate color scheme preferences without changing your OS settings. Open DevTools, go to the Rendering tab, and find the "Emulate CSS media feature prefers-color-scheme" dropdown. This is invaluable for testing both themes quickly during development.

A good dark mode implementation reads the system preference as the default starting point and applies it immediately. This shows respect for the user accessibility setting. Only after the user explicitly toggles the theme in your app should you store and use a different override.

On the server, window.matchMedia does not exist. If you render on the server, guard with typeof window !== 'undefined' before calling matchMedia. For SSR apps, read the user preference from a cookie or HTTP header instead to avoid hydration mismatches.

What property of a MediaQueryList object tells you whether the media query currently matches?

The prefers-color-scheme media query exposes the OS color preference in both CSS and JavaScript. Use window.matchMedia to read and listen for changes, always clean up event listeners, and distinguish system defaults from user overrides. Chrome DevTools emulation speeds up testing both themes.