Detectando o esquema de cores do sistema

A consulta de mídia prefers-color-scheme do CSS detecta se o usuário configurou o sistema operacional para usar um tema de cores escuro ou claro. Ela aceita dois valores: dark e light. Essa preferência é definida no nível do OS, nas configurações do sistema, e não no navegador.

Você pode aplicar estilos escuros exclusivamente no CSS usando @media (prefers-color-scheme: dark) { ... }. Dentro desse bloco, substitua cores, planos de fundo e bordas para adequá-los a uma paleta escura. Essa abordagem não exige JavaScript e funciona mesmo antes de o React ser montado.

Em JavaScript, window.matchMedia('(prefers-color-scheme: dark)') retorna um objeto MediaQueryList. Você pode usá-lo para ler programaticamente a preferência atual do sistema dentro de hooks do React ou manipuladores de eventos. Essa é a ponte entre as consultas de mídia do CSS e a sua lógica em JS.

O objeto MediaQueryList tem uma propriedade matches que retorna um booleano. Se matches for true, o sistema estará no modo escuro; se for false, estará no modo claro. Normalmente, você lê esse valor uma vez durante a montagem para inicializar o estado do tema.

Os usuários podem alterar o esquema de cores do OS a qualquer momento. Para responder dinamicamente, chame mediaQuery.addEventListener('change', handler), em que handler recebe o MediaQueryListEvent atualizado. O objeto do evento também tem um booleano matches que representa a nova preferência.

Uma abordagem organizada é criar um hook personalizado usando useSyncExternalStore. O hook se inscreve em mediaQuery.addEventListener e fornece uma função de instantâneo que retorna mediaQuery.matches. Isso mantém o hook sincronizado com a API externa do navegador sem gerenciamento manual de estado.

Quando o componente é desmontado, você deve remover o ouvinte de eventos para evitar vazamentos de memória. Na limpeza de um useEffect, chame mediaQuery.removeEventListener('change', handler). Com useSyncExternalStore, a função de assinatura deve retornar uma função de cancelamento que faça o mesmo.

A preferência do sistema é o que o OS informa. Porém, os usuários geralmente querem substituir o tema do aplicativo de forma independente, por exemplo, mantendo o aplicativo claro enquanto o OS está no modo escuro. Sua arquitetura deve distinguir entre o padrão do sistema e uma substituição explícita do usuário armazenada no localStorage.

O Chrome DevTools permite emular preferências de esquema de cores sem alterar as configurações do OS. Abra o DevTools, acesse a guia Renderização e localize a lista suspensa "Emular o recurso de mídia CSS prefers-color-scheme". Isso é muito útil para testar rapidamente os dois temas durante o desenvolvimento.

Uma boa implementação do modo escuro lê a preferência do sistema como ponto de partida padrão e a aplica imediatamente. Isso demonstra respeito à configuração de acessibilidade do usuário. Somente depois que o usuário alternar explicitamente o tema no aplicativo você deve armazenar e usar uma substituição diferente.

No servidor, window.matchMedia não existe. Se você fizer a renderização no servidor, use typeof window !== 'undefined' como proteção antes de chamar matchMedia. Em aplicativos com SSR, leia a preferência do usuário de um cookie ou cabeçalho HTTP para evitar incompatibilidades de hidratação.

Qual propriedade de um objeto MediaQueryList informa se a consulta de mídia corresponde atualmente?

A consulta de mídia prefers-color-scheme expõe a preferência de cores do OS tanto no CSS quanto no JavaScript. Use window.matchMedia para ler alterações e escutá-las, sempre remova os ouvintes de eventos e diferencie os padrões do sistema das substituições do usuário. A emulação no Chrome DevTools acelera os testes dos dois temas.