> ## Documentation Index
> Fetch the complete documentation index at: https://devkit4ai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Theme Configuration
> Control light and dark themes with next-themes and shared Tailwind tokens.
The Starter Kit includes a complete dark mode implementation using `next-themes` and Tailwind CSS. Users can toggle between light, dark, and system themes with their preference persisted across sessions.
## Overview
The theme system provides:
* **Light and dark mode** with instant switching
* **System preference detection** that respects OS settings
* **Persistent user selection** stored in localStorage
* **No flash of unstyled content** on page load
* **Tailwind integration** using `dark:` class modifiers
## Architecture
### ThemeProvider Setup
The theme system is initialized in the root layout:
```tsx app/layout.tsx theme={null}
import { ThemeProvider } from 'next-themes'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
How the theme is applied. Using `"class"` enables Tailwind's `dark:` modifiers.
The default theme when no preference is stored. `"system"` follows the OS preference.
Allows detecting and using the system theme preference.
Prevents CSS transitions during theme switches for instant changes. Set to `true` to avoid visual glitches.
The `suppressHydrationWarning` prop on the `` element prevents hydration warnings caused by `next-themes` modifying the class attribute before React hydrates.
### ThemeSwitcher Component
The header includes a theme toggle button:
```tsx components/theme-switcher.tsx theme={null}
'use client'
import { Moon, Sun } from 'lucide-react'
import { useTheme } from 'next-themes'
import { useEffect, useState } from 'react'
import { Button } from '@/components/ui/button'
export function ThemeSwitcher() {
const [mounted, setMounted] = useState(false)
const { theme, setTheme } = useTheme()
useEffect(() => {
setMounted(true)
}, [])
if (!mounted) {
return null
}
return (
)
}
```
The component returns `null` until mounted to prevent hydration mismatches, since the theme is determined client-side.
## Tailwind Configuration
### Enabling Dark Mode
Dark mode is enabled in `tailwind.config.ts`:
```typescript tailwind.config.ts theme={null}
import type { Config } from "tailwindcss";
const config: Config = {
content: [
"./pages/**/*.{js,ts,jsx,tsx,mdx}",
"./components/**/*.{js,ts,jsx,tsx,mdx}",
"./app/**/*.{js,ts,jsx,tsx,mdx}",
],
darkMode: "class", // Enable class-based dark mode
theme: {
extend: {
// Your theme customizations
},
},
plugins: [],
};
export default config;
```
Set to `"class"` to use `next-themes` with Tailwind's `dark:` modifier. The alternative `"media"` uses CSS media queries only.
### Dark Mode Color Palette
Define colors that work in both themes:
```typescript tailwind.config.ts theme={null}
const config: Config = {
theme: {
extend: {
colors: {
// Semantic colors that adapt to theme
background: {
DEFAULT: '#ffffff',
dark: '#0a0a0a',
},
foreground: {
DEFAULT: '#0a0a0a',
dark: '#ffffff',
},
// Component-specific colors
card: {
DEFAULT: '#ffffff',
dark: '#171717',
},
'card-foreground': {
DEFAULT: '#0a0a0a',
dark: '#fafafa',
},
border: {
DEFAULT: '#e5e5e5',
dark: '#262626',
},
// Brand colors with dark variants
primary: {
50: '#f0fdf4',
100: '#dcfce7',
200: '#bbf7d0',
300: '#86efac',
400: '#4ade80',
500: '#22c55e',
600: '#16a34a',
700: '#15803d',
800: '#166534',
900: '#14532d',
950: '#052e16',
},
},
},
},
};
```
## Styling Components for Dark Mode
### Basic Dark Mode Styles
Use Tailwind's `dark:` modifier to apply dark mode styles:
```tsx theme={null}
```
Using HSL color values in CSS variables makes it easy to adjust saturation and lightness programmatically.
## Advanced Theme Patterns
### Multi-Theme Dropdown
Create a full theme selector with light, dark, and system options:
```tsx components/theme-selector.tsx theme={null}
'use client'
import { Check, Moon, Sun, Monitor } from 'lucide-react'
import { useTheme } from 'next-themes'
import { useEffect, useState } from 'react'
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu'
import { Button } from '@/components/ui/button'
export function ThemeSelector() {
const [mounted, setMounted] = useState(false)
const { theme, setTheme } = useTheme()
useEffect(() => {
setMounted(true)
}, [])
if (!mounted) {
return null
}
const themes = [
{ value: 'light', label: 'Light', icon: Sun },
{ value: 'dark', label: 'Dark', icon: Moon },
{ value: 'system', label: 'System', icon: Monitor },
]
return (
{themes.map((t) => (
setTheme(t.value)}
className="cursor-pointer"
>
{t.label}
{theme === t.value && }
))}
)
}
```
### Detecting System Theme
Access the resolved theme (accounting for system preference):
```tsx theme={null}
'use client'
import { useTheme } from 'next-themes'
export function ThemedComponent() {
const { theme, resolvedTheme } = useTheme()
// theme: 'light' | 'dark' | 'system'
// resolvedTheme: 'light' | 'dark' (actual computed theme)
return (
Selected: {theme}
Active: {resolvedTheme}
)
}
```
### Conditional Rendering
Render different content based on theme:
```tsx theme={null}
import { useTheme } from 'next-themes'
export function ThemedImage() {
const { resolvedTheme } = useTheme()
return (
)
}
```
## Custom Color Schemes
### Creating Theme Variants
Define multiple color schemes:
```css app/globals.css theme={null}
:root {
--theme-blue-primary: 219 95% 55%;
--theme-green-primary: 142 76% 45%;
--theme-purple-primary: 271 81% 56%;
}
[data-color-scheme="blue"] {
--primary: var(--theme-blue-primary);
}
[data-color-scheme="green"] {
--primary: var(--theme-green-primary);
}
[data-color-scheme="purple"] {
--primary: var(--theme-purple-primary);
}
```
Implement color scheme switching:
```tsx theme={null}
'use client'
import { useEffect, useState } from 'react'
export function ColorSchemeSelector() {
const [scheme, setScheme] = useState('blue')
useEffect(() => {
document.documentElement.setAttribute('data-color-scheme', scheme)
}, [scheme])
return (
)
}
```
## Best Practices
Use semantic color names like `background`, `foreground`, `border` instead of specific colors like `white` or `gray-900`. This makes theme changes easier.
```tsx theme={null}
// Good
// Avoid
```
Always test your UI in both light and dark modes. Colors that work in light mode may have insufficient contrast in dark mode.
Ensure WCAG AA contrast ratios (4.5:1 for text) in both themes. Use tools like [Contrast Checker](https://webaim.org/resources/contrastchecker/).
Set `disableTransitionOnChange` to prevent CSS transitions from animating during theme switches, which can cause visual glitches.
For logos and images, provide theme-specific variants or use images that work in both themes. Transparent PNGs and SVGs work best.
`next-themes` automatically persists the user's theme preference in localStorage. No additional code needed.
## Accessibility Considerations
### Respecting System Preferences
The default `system` theme respects the user's OS-level preference:
```tsx theme={null}
```
This ensures users who have set a dark mode preference at the OS level see dark mode by default.
### Reduced Motion
Respect the `prefers-reduced-motion` setting:
```css theme={null}
@media (prefers-reduced-motion: reduce) {
* {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
```
### Focus Indicators
Ensure focus indicators are visible in both themes:
```tsx theme={null}
```
## Troubleshooting
If you see a flash when the page loads, ensure `suppressHydrationWarning` is on the `` element:
```tsx theme={null}
```
Ensure `next-themes` can access localStorage. Check browser settings and privacy modes. The theme is stored in `localStorage.theme`.
If theme toggle icons don't switch properly, verify both icons are present and CSS transitions are working:
```tsx theme={null}
```
If you see hydration errors, ensure theme-dependent components use the mounted check:
```tsx theme={null}
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return null
```
## Next Steps
Apply your brand colors and visual identity
Configure navigation and layout settings
Explore theme-aware UI components
Create custom pages with dark mode support