Dark Mode (next-themes)

Install

npm install next-themes

Provider

// components/providers/theme-provider.tsx
"use client";
import { ThemeProvider as NextThemesProvider } from "next-themes";

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  return (
    <NextThemesProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
      {children}
    </NextThemesProvider>
  );
}

Wrap in root layout inside <body>.

HTML attribute

<html lang="en" suppressHydrationWarning>

Required — theme class applied to <html> before hydration.

Tailwind v4 dark variant

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

Components: bg-white dark:bg-slate-900 text-slate-900 dark:text-slate-100.

CSS variables approach

:root { --background: #f8fafc; --foreground: #0a1929; }
.dark { --background: #0a1929; --foreground: #f0f4f8; color-scheme: dark; }

Use semantic tokens (bg-background) mapped in @theme.

Theme toggle

"use client";
import { useTheme } from "next-themes";
import { Moon, Sun } from "lucide-react";

export function ThemeToggle() {
  const { theme, setTheme, resolvedTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return <Button variant="ghost" size="icon" aria-label="Toggle theme" />;

  return (
    <Button
      variant="ghost"
      size="icon"
      aria-label="Toggle theme"
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
    >
      {resolvedTheme === "dark" ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
    </Button>
  );
}

Mount guard prevents hydration mismatch on icon.

Touch target

Mobile toggle: minimum 44×44px hit area (size="icon" + padding or min-h-11 min-w-11).

Charts / images in dark mode

• Recharts: set axis/grid stroke colors for dark backgrounds
• Export capture: test both themes; some libs capture computed styles at click time

Anti-patterns

• Storing theme only in localStorage without next-themes (flash on load)
• Hardcoded light colors without dark: counterparts on marketing + app shells
• enableTransitionOnChange with heavy CSS transitions (jarring theme switch)

Pair with: tailwind-css-v4, nextjs-ui-foundation.