Dark Mode Implementation

Dark Mode Implementation

Overview

Tailwind v4 + shadcn/ui dark mode requires:

1. ThemeProvider component to manage state
2. .dark class toggling on <html> element
3. localStorage persistence
4. System theme detection

ThemeProvider Component

Full Implementation

// src/components/theme-provider.tsx
import { createContext, useContext, useEffect, useState, ReactNode } from 'react'

type Theme = 'dark' | 'light' | 'system'

type ThemeProviderProps = {
  children: ReactNode
  defaultTheme?: Theme
  storageKey?: string
}

type ThemeProviderState = {
  theme: Theme
  setTheme: (theme: Theme) => void
}

const initialState: ThemeProviderState = {
  theme: 'system',
  setTheme: () => null,
}

const ThemeProviderContext = createContext<ThemeProviderState>(initialState)

export function ThemeProvider({
  children,
  defaultTheme = 'system',
  storageKey = 'vite-ui-theme',
  ...props
}: ThemeProviderProps) {
  const [theme, setTheme] = useState<Theme>(() => {
    try {
      return (localStorage.getItem(storageKey) as Theme) || defaultTheme
    } catch (e) {
      return defaultTheme
    }
  })

  useEffect(() => {
    const root = window.document.documentElement
    root.classList.remove('light', 'dark')

    if (theme === 'system') {
      const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
        .matches ? 'dark' : 'light'
      root.classList.add(systemTheme)
      return
    }

    root.classList.add(theme)
  }, [theme])

  const value = {
    theme,
    setTheme: (theme: Theme) => {
      try {
        localStorage.setItem(storageKey, theme)
      } catch (e) {
        console.warn('Storage unavailable')
      }
      setTheme(theme)
    },
  }

  return (
    <ThemeProviderContext.Provider {...props} value={value}>
      {children}
    </ThemeProviderContext.Provider>
  )
}

export const useTheme = () => {
  const context = useContext(ThemeProviderContext)
  if (context === undefined)
    throw new Error('useTheme must be used within a ThemeProvider')
  return context
}

Wrap Your App

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

Theme Toggle Component

Using shadcn/ui Dropdown Menu

pnpm dlx shadcn@latest add dropdown-menu

// src/components/mode-toggle.tsx
import { Moon, Sun } from "lucide-react"
import { Button } from "@/components/ui/button"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { useTheme } from "@/components/theme-provider"

export function ModeToggle() {
  const { setTheme } = useTheme()

  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline" size="icon">
          <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
          <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
          <span className="sr-only">Toggle theme</span>
        </Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="end">
        <DropdownMenuItem => setTheme("light")}>
          Light
        </DropdownMenuItem>
        <DropdownMenuItem => setTheme("dark")}>
          Dark
        </DropdownMenuItem>
        <DropdownMenuItem => setTheme("system")}>
          System
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  )
}

How It Works

Theme Flow

User selects theme → setTheme() called
  ↓
Save to localStorage
  ↓
Update state
  ↓
useEffect triggers
  ↓
Remove existing classes (.light, .dark)
  ↓
Add new class to <html>
  ↓
CSS variables update (.dark overrides :root)
  ↓
UI updates automatically

System Theme Detection

if (theme === 'system') {
  const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
    .matches ? 'dark' : 'light'
  root.classList.add(systemTheme)
}

This respects the user's OS preference when "System" is selected.

Common Issues

Issue: Dark mode not switching

Cause: Theme provider not wrapping app Fix: Ensure <ThemeProvider> wraps your app in main.tsx

Issue: Theme resets on page refresh

Cause: localStorage not working Fix: Check browser privacy settings, add sessionStorage fallback

Issue: Flash of wrong theme on load

Cause: Theme applied after initial render Fix: Add inline script to index.html (advanced)

Issue: Icons not changing

Cause: CSS transitions not working Fix: Verify icon classes use dark: variants for animations

Testing Checklist

• Light mode displays correctly
• Dark mode displays correctly
• System mode respects OS setting
• Theme persists after page refresh
• Toggle component shows current state
• All text has proper contrast
• No flash of wrong theme on load
• Works in incognito mode (graceful fallback)

Official Documentation

• shadcn/ui Dark Mode (Vite): https://ui.shadcn.com/docs/dark-mode/vite
• Tailwind Dark Mode: https://tailwindcss.com/docs/dark-mode