shadcn/ui Dark Mode Not Working— next-themes Setup [Fixed 2026]
Also covers: ThemeProvider · CSS variables dark block · hydration mismatch · FOIT · theme toggle button
⚡ The Symptom
// Theme toggle fires but components stay in light mode
// OR:
// Dark mode works but flashes white on every page load
// OR:
// Hydration mismatch warning in console✅ Setup sequence
npm install next-themesWhy shadcn/ui Dark Mode Doesn't Toggle
shadcn/ui uses Tailwind's class dark mode strategy — it reads the dark class on the html element. If that class never gets added, no dark mode applies. The two most common causes are: ThemeProvider not wrapping the app, and the dark CSS variable block missing from globals.css.
Install and Configure next-themes
Foundation — theme state managerimport type { Config } from "tailwindcss"
const config: Config = {
darkMode: ["class"], // ← must be "class" not "media" for next-themes
content: [
"./app/**/*.{ts,tsx}",
"./components/**/*.{ts,tsx}",
],
// ... rest of config
}
export default configWrap Your App in ThemeProvider
ThemeProvider must wrap the entire app"use client"
import { ThemeProvider as NextThemesProvider } from "next-themes"
import type { ThemeProviderProps } from "next-themes/dist/types"
export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
return <NextThemesProvider {...props}>{children}</NextThemesProvider>
}import { ThemeProvider } from "@/components/theme-provider"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning> {/* ← suppressHydrationWarning is required */}
<body>
<ThemeProvider
attribute="class" // adds/removes "dark" class on <html>
defaultTheme="system" // follow OS preference by default
enableSystem // enable system theme detection
disableTransitionOnChange // prevent flash during theme change
>
{children}
</ThemeProvider>
</body>
</html>
)
}Add Dark CSS Variables to globals.css
Dark class applied but colors don't change@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--primary: 222.2 47.4% 11.2%;
--primary-foreground: 210 40% 98%;
--border: 214.3 31.8% 91.4%;
/* ... all light mode variables */
}
/* ← This dark block is required — without it nothing changes in dark mode */
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
--primary: 210 40% 98%;
--primary-foreground: 222.2 47.4% 11.2%;
--border: 217.2 32.6% 17.5%;
/* ... all dark mode overrides */
}
}The shadcn init command generates a complete .dark {} block for your chosen color palette. If you ran init, this block should already be in globals.css. Check if it's there before adding manually.
Fix Hydration Mismatch
Console warning about class attribute mismatchWhen Next.js renders on the server, it doesn't know the user's theme preference (stored in localStorage). The suppressHydrationWarning attribute on html tells React not to warn about this expected mismatch.
"use client"
import { useTheme } from "next-themes"
import { useEffect, useState } from "react"
export function ThemeToggle() {
const { theme, setTheme } = useTheme()
const [mounted, setMounted] = useState(false)
// ✅ Wait for component to mount before reading theme
// Prevents hydration mismatch in the toggle button icon
useEffect(() => setMounted(true), [])
if (!mounted) return null // render nothing on server
return (
<button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
{theme === "dark" ? "🌙" : "☀️"}
</button>
)
}Build a Complete Theme Toggle Button
Polished toggle with Sun/Moon icons"use client"
import { useTheme } from "next-themes"
import { useEffect, useState } from "react"
import { Button } from "@/components/ui/button"
import {
DropdownMenu, DropdownMenuContent,
DropdownMenuItem, DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
export function ThemeToggle() {
const { setTheme } = useTheme()
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return <Button variant="ghost" size="icon" disabled><span className="sr-only">Toggle theme</span></Button>
return (
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button variant="ghost" size="icon">
{/* Sun icon — visible in light mode */}
<span className="h-4 w-4 dark:hidden">☀️</span>
{/* Moon icon — visible in dark mode */}
<span className="h-4 w-4 hidden dark:block">🌙</span>
<span className="sr-only">Toggle theme</span>
</Button>
</DropdownMenuTrigger>
<DropdownMenuContent align="end">
<DropdownMenuItem onClick={() => setTheme("light")}>Light</DropdownMenuItem>
<DropdownMenuItem onClick={() => setTheme("dark")}>Dark</DropdownMenuItem>
<DropdownMenuItem onClick={() => setTheme("system")}>System</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
)
}Prevention
- Set darkMode: ['class'] in tailwind.config.ts — next-themes requires class strategy
- Add suppressHydrationWarning to the <html> element — prevents React warnings about class mismatch
- Ensure the .dark {} CSS variable block exists in globals.css — this is what actually changes the colors
- Wrap the entire app in ThemeProvider in layout.tsx — not just individual pages
- Use a mounted guard (useEffect + useState) in toggle components to prevent hydration mismatch
- Use attribute='class' in ThemeProvider — this is what adds the dark class to <html>
Frequently Asked Questions
How does shadcn/ui implement dark mode?+−
Do I need next-themes for dark mode with shadcn/ui?+−
Why does my dark mode flash white on page load?+−
Why do shadcn components not change color in dark mode?+−
Can I force dark mode always without a toggle?+−
How do I access the current theme in a component?+−
Need Expert Help?
We Build Dark Mode UI with shadcn/ui
Softplix engineers set up shadcn/ui with full dark mode, custom themes, and accessible design systems. Let us help.
Talk to an Engineer