Dark Mode com Tailwind CSS no React: Guia Passo a Passo

Dark Mode com Tailwind CSS no React: Guia Passo a Passo

Para fazer dark mode com Tailwind CSS em um projeto React, você usa a variante dark: nas classes utilitárias e decide como o modo escuro é ativado: automaticamente pela preferência do sistema operacional ou manualmente por um botão que adiciona a classe dark no elemento <html>. A segunda opção é a mais usada em sites profissionais, porque dá controle ao usuário e permite salvar a escolha.

Como o dark mode do Tailwind funciona

A variante dark: aplica um estilo apenas quando o modo escuro está ativo. Por exemplo, bg-white dark:bg-slate-900 deixa o fundo branco no tema claro e azul bem escuro no tema escuro.

Segundo a documentação oficial do Tailwind CSS, por padrão a variante dark: usa a media query prefers-color-scheme, ou seja, segue a configuração do sistema do visitante. Isso funciona sem nenhuma configuração extra.

Existem duas estratégias principais:

• Automática: o site segue o tema do sistema operacional, sem botão.
• Manual (por classe): você controla o tema com uma classe dark no <html> e pode oferecer um botão de alternância.

Configurando o modo escuro manual no Tailwind v4

No Tailwind CSS v4, a configuração é feita direto no arquivo CSS, sem tailwind.config.js. Para trocar a estratégia padrão por uma baseada em classe, declare uma variante customizada no seu CSS principal:

@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));

Com isso, qualquer elemento dentro de um pai com a classe dark passa a respeitar as classes dark:. No Tailwind v3, o equivalente era darkMode: 'class' no arquivo de configuração.

Criando o botão de alternância no React

Em um projeto React com Vite, o caminho mais simples é um hook que guarda o tema, atualiza a classe no <html> e salva a escolha no localStorage.

import { useEffect, useState } from "react";

export function useTheme() {
  const [theme, setTheme] = useState(() => {
    return localStorage.getItem("theme") ||
      (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
  });

  useEffect(() => {
    document.documentElement.classList.toggle("dark", theme === "dark");
    localStorage.setItem("theme", theme);
  }, [theme]);

  return { theme, toggle: () => setTheme(t => (t === "dark" ? "light" : "dark")) };
}

O hook primeiro procura a escolha salva do usuário. Se não existir, usa a preferência do sistema por meio de window.matchMedia. Depois, qualquer mudança é aplicada ao <html> e persistida.

Como evitar o flash de tema errado

Um problema comum é o "flash": a página carrega clara e só depois troca para escura, porque o React demora alguns instantes para executar o hook. A solução é rodar um pequeno script no <head> do index.html, antes de a página ser desenhada:

<script>
  const saved = localStorage.getItem("theme");
  const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
  if (saved === "dark" || (!saved && prefersDark)) {
    document.documentElement.classList.add("dark");
  }
</script>

Esse script é síncrono e leve, então o tema correto já está aplicado no primeiro render.

Boas práticas de design para o modo escuro

Dark mode não é só inverter cores. Algumas regras ajudam a manter a qualidade:

1. Evite preto puro (#000) no fundo. Tons como slate-900 ou zinc-900 cansam menos a vista.
2. Reduza o brilho de textos brancos, usando algo como slate-200 em vez de white.
3. Verifique o contraste. As diretrizes WCAG da W3C recomendam razão mínima de 4,5:1 para texto comum.
4. Teste imagens e logos: logos escuros podem sumir no fundo escuro e precisam de uma versão alternativa.
5. Use variáveis CSS ou tokens de cor para não repetir dark: em todo elemento.

Perguntas Frequentes

Como ativar o dark mode no Tailwind CSS? Use a variante dark: nas classes. Por padrão ela segue o tema do sistema. Para controlar por botão, configure a estratégia por classe e adicione dark ao elemento <html>.

Preciso de tailwind.config.js no Tailwind v4? Não. No Tailwind v4 a configuração fica no CSS, e o modo escuro por classe é definido com @custom-variant dark.

Como salvar a escolha de tema do usuário? Guarde o valor no localStorage e leia-o ao carregar a página. Se não houver valor salvo, use prefers-color-scheme como padrão.

Por que minha página pisca no tema claro antes de ficar escura? Porque o tema só é aplicado depois que o React carrega. Resolva com um script inline no <head> que adiciona a classe dark antes da renderização.

Dark mode melhora o SEO? Não diretamente. Ele melhora a experiência do usuário, o que ajuda indiretamente, mas o foco de SEO continua em conteúdo, velocidade e acessibilidade.

Conclusão

Implementar dark mode com Tailwind CSS no React é rápido: defina a estratégia por classe, crie um hook com localStorage e adicione o script anti-flash no <head>. Com isso você entrega um site moderno e confortável em qualquer ambiente. Se você precisa de um site, sistema ou landing page com esse nível de acabamento, a Stormcore atua com criação de sites, automações, sistemas e gestão de redes sociais.