Определение системной цветовой схемы

Медиазапрос CSS prefers-color-scheme определяет, настроил ли пользователь свою операционную систему на тёмную или светлую цветовую тему. Он принимает два значения: dark и light. Эта настройка задаётся на уровне OS в системных параметрах, а не в браузере.

Вы можете применять тёмные стили только средствами CSS с помощью @media (prefers-color-scheme: dark) { ... }. Внутри этого блока переопределите цвета, фоны и границы в соответствии с тёмной палитрой. Такой подход не требует JavaScript и работает ещё до монтирования React.

В JavaScript вызов window.matchMedia('(prefers-color-scheme: dark)') возвращает объект MediaQueryList. С его помощью можно программно прочитать текущую системную настройку внутри хуков React или обработчиков событий. Это связующее звено между медиазапросами CSS и логикой JS.

У объекта MediaQueryList есть свойство matches, возвращающее логическое значение. Если matches равно true, система использует тёмный режим; если false — светлый. Обычно это значение считывают один раз при монтировании, чтобы инициализировать состояние темы.

Пользователь может в любой момент изменить цветовую схему OS. Чтобы динамически реагировать на это, вызовите mediaQuery.addEventListener('change', handler), где handler получает обновлённый объект MediaQueryListEvent. Объект события также содержит логическое свойство matches, отражающее новую настройку.

Удобный подход — создать пользовательский хук с помощью useSyncExternalStore. Хук подписывается через mediaQuery.addEventListener и предоставляет функцию снимка, возвращающую mediaQuery.matches. Благодаря этому хук синхронизирован с внешним API браузера без ручного управления состоянием.

При размонтировании компонента необходимо удалить обработчик события, чтобы избежать утечек памяти. В функции очистки useEffect вызовите mediaQuery.removeEventListener('change', handler). При использовании useSyncExternalStore функция подписки должна возвращать функцию отмены подписки, выполняющую то же действие.

Системная настройка — это значение, которое сообщает OS. Но пользователи часто хотят независимо переопределять тему приложения, например оставлять приложение светлым, когда OS использует тёмный режим. В архитектуре следует различать системное значение по умолчанию и явное переопределение пользователя, сохранённое в localStorage.

Chrome DevTools позволяет эмулировать настройки цветовой схемы без изменения параметров OS. Откройте DevTools, перейдите на вкладку отрисовки и найдите раскрывающийся список «Эмулировать медиафункцию CSS prefers-color-scheme». Это незаменимо для быстрой проверки обеих тем во время разработки.

Хорошая реализация тёмного режима считывает системную настройку как начальное значение по умолчанию и применяет её сразу. Это демонстрирует уважение к настройке доступности пользователя. Только после явного переключения темы в приложении следует сохранять и использовать другое переопределение.

На сервере window.matchMedia не существует. При серверном рендеринге перед вызовом matchMedia проверьте условие typeof window !== 'undefined'. В приложениях с SSR вместо этого считывайте настройку пользователя из cookie или HTTP-заголовка, чтобы избежать несоответствий при гидратации.

Какое свойство объекта MediaQueryList сообщает, соответствует ли ему медиазапрос в данный момент?

Медиазапрос prefers-color-scheme предоставляет настройку цвета OS и в CSS, и в JavaScript. Используйте window.matchMedia для чтения настройки и отслеживания изменений, всегда удаляйте обработчики событий и различайте системные значения по умолчанию и пользовательские переопределения. Эмуляция в Chrome DevTools ускоряет проверку обеих тем.