Tailwind CSS 4: dark mode não funciona? Veja as causas e como corrigir
Se o Tailwind CSS 4: dark mode não funciona, você não está sozinho.
Esse é um dos problemas mais comuns depois de atualizar o Tailwind ou iniciar um projeto novo — e, na maioria das vezes, não é bug, é configuração.
Neste artigo, você vai entender por que o dark mode no Tailwind CSS 4 não funciona, os erros mais comuns e como corrigir passo a passo, sem gambiarras.
Resumo rápido (pra quem está com pressa)
👉 Na maioria dos casos, o dark mode no Tailwind CSS 4 não funciona porque:
- o
darkModenão está configurado corretamente - a classe
darknão está aplicada no elemento certo - o estado do tema não está consistente (especialmente em React/Next.js)
Agora vamos aos detalhes.
Como funciona o dark mode no Tailwind CSS
O Tailwind suporta duas estratégias principais de dark mode:
🌙 media
Baseado na preferência do sistema operacional:
darkMode: 'media'O navegador decide automaticamente se o modo escuro será aplicado.
🌗 class (a mais usada)
Você controla o tema manualmente usando a classe dark:
darkMode: 'class'Exemplo:
<html class="dark">A maioria dos projetos modernos usa class, porque:
- permite botão de alternância
- funciona melhor com React / Next.js
- dá mais controle ao usuário
O erro mais comum: dark mode configurado errado
No Tailwind CSS 4, o arquivo de configuração continua sendo essencial.
Exemplo correto:
// tailwind.config.js
export default {
darkMode: 'class',
content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
theme: {
extend: {},
},
plugins: [],
}Erros comuns aqui:
- esquecer o
darkMode - configurar como
mediaachando que está usandoclass - alterar o arquivo e não reiniciar o servidor
👉 Qualquer erro aqui faz o dark mode simplesmente não funcionar.
Classe dark aplicada no lugar errado
Mesmo com a config certa, o dark mode não funciona se a classe dark estiver no lugar errado.
❌ Exemplo problemático
<body class="dark">
<div class="bg-white dark:bg-black">...</div>
</body>Dependendo do framework, isso pode não funcionar como esperado.
✅ Forma recomendada
<html class="dark">
<body>
<div class="bg-white dark:bg-black">...</div>
</body>
</html>👉 A classe dark deve estar no topo da árvore DOM, geralmente no <html>.
Dark mode não funciona em componentes React
Outro erro muito comum é tentar controlar o tema dentro de um componente, sem garantir que a classe está aplicada globalmente.
Exemplo problemático:
<div className={dark ? 'dark' : ''}>
<div className="bg-white dark:bg-black">
Conteúdo
</div>
</div>Isso nem sempre funciona bem, especialmente em aplicações maiores.
👉 O ideal é aplicar a classe dark no elemento raiz, não em componentes isolados.
Dark mode não funciona no Next.js
👉 Veja também “Erros de hidratação são uma das causas mais comuns desse tipo de comportamento.”
Aqui entra uma dor real.
No Next.js, o dark mode costuma quebrar por causa de:
- Server Side Rendering (SSR)
- estado inicial inconsistente
- leitura do tema no
localStorage
Exemplo clássico de problema
const [theme, setTheme] = useState(
localStorage.getItem('theme')
);No servidor:
localStoragenão existe
No cliente:
- existe
Resultado:
- hidratação inconsistente
- dark mode falhando ou piscando
Forma correta de lidar com isso
const [theme, setTheme] = useState(null);
useEffect(() => {
setTheme(localStorage.getItem('theme'));
}, []);E então aplicar a classe:
E então aplicar a classe:
useEffect(() => {
if (theme === 'dark') {
document.documentElement.classList.add('dark');
} else {
document.documentElement.classList.remove('dark');
}
}, [theme]);Isso mantém:
- HTML consistente
- dark mode previsível
- menos bugs
Tailwind CSS 4 e problemas de cache / build
👉 Veja também “Problemas de cache e build também são uma causa comum de erros em aplicações backend.”
Muita gente esquece disso.
Você muda a config, salva… e nada acontece.
Possíveis causas:
- servidor de desenvolvimento não foi reiniciado
- cache do Vite / Next.js
- build antigo em produção
Checklist rápido
- pare o servidor
- rode novamente
npm run dev - se for produção, gere novo build
Isso resolve mais problemas do que parece.
Como corrigir o dark mode no Tailwind CSS 4 (passo a passo)
Use este checklist:
1️⃣ Confirme que darkMode: 'class' está configurado
2️⃣ Aplique a classe dark no <html>
3️⃣ Garanta que o estado do tema é consistente
4️⃣ Evite valores dinâmicos no render inicial
5️⃣ Reinicie o servidor após mudar a config
Se seguir isso, o dark mode funciona.
Quando o problema NÃO é o Tailwind
Às vezes o Tailwind está certo, mas outra coisa quebra o visual:
- CSS global sobrescrevendo estilos
- bibliotecas externas com estilos próprios
- conflitos de especificidade
Se a classe dark: está sendo aplicada (você vê no DOM), mas o visual não muda, o problema é CSS, não Tailwind.
Uma dica prática para devs cansados
👉 Veja também “Esse comportamento está diretamente ligado ao funcionamento do useEffect no React.”
Dark mode é aquele tipo de problema que faz você:
- duvidar do Tailwind
- mexer em classe sem parar
- achar que tudo está quebrado
Na maioria das vezes, é um detalhe pequeno de configuração.
Entender como o dark mode funciona de verdade evita horas perdidas e frustração desnecessária.
Conclusão
Se o dark mode não funciona no Tailwind CSS 4:
- ❌ não é bug na maioria dos casos
- ✅ é configuração ou aplicação incorreta da classe
- ✅ resolver exige olhar o fluxo completo (config → DOM → estado)
Agora você sabe onde olhar, o que corrigir e como evitar esse problema no futuro.
