# Dark Mode Toggle
Flash-free dark mode for Next.js 14+ with Tailwind — three-way light/dark/system toggle, localStorage persistence, OS preference sync, and hydration-safe rendering.
## What's included
- `ThemeProvider` — context provider; reads localStorage on mount, listens for OS preference changes when mode is `system`
- `useTheme()` — returns `{ theme, resolved, setTheme, cycleTheme }` — `theme` is the stored preference, `resolved` is always `'light'` or `'dark'`
- `ThemeToggle` — button that cycles light → dark → system; renders a fixed-size placeholder before mount to prevent layout shift
- `THEME_SCRIPT` — inline script string to paste into `` before stylesheets; eliminates flash of wrong theme on first load
- `useColorScheme()` — standalone hook returning the OS preference; usable without `ThemeProvider`
- `Theme` type — `'light' | 'dark' | 'system'`
- `ResolvedTheme` type — `'light' | 'dark'`
## Setup
### 1. Install dependencies
No extra packages — only React and Tailwind, which you already have.
### 2. Inject the no-flash script
```tsx
// app/layout.tsx
import { THEME_SCRIPT } from '@/blocks/darkmode'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{/* stylesheets go after */}
{children}
)
}
```
### 3. Wrap your app
```tsx
// app/providers.tsx
'use client'
import { ThemeProvider } from '@/blocks/darkmode'
export function Providers({ children }: { children: React.ReactNode }) {
return {children}
}
```
```tsx
// app/layout.tsx — inside
import { Providers } from './providers'
{children}
```
### 4. Tailwind config
```js
// tailwind.config.js
module.exports = {
darkMode: 'class',
// ...
}
```
### 5. CSS variables (globals.css)
```css
:root { --bg: #fff; --text: #111; --border: #d1d5db; }
.dark { --bg: #100F0A; --text: #F4F3EF; --border: #374151; }
```
## Usage examples
```tsx
// Drop-in toggle button — put it in your navbar
import { ThemeToggle } from '@/blocks/darkmode'
// icon only
// icon + "Light" / "Dark" / "System" label
```
```tsx
// Programmatic control
'use client'
import { useTheme } from '@/blocks/darkmode'
export function ThemeSelect() {
const { theme, setTheme } = useTheme()
return (
)
}
```
```tsx
// Read resolved theme to swap assets
'use client'
import { useTheme } from '@/blocks/darkmode'
export function Logo() {
const { resolved } = useTheme()
return 
}
```
## Notes
- `suppressHydrationWarning` on `` is required — the no-flash script mutates the DOM before React hydrates, which would otherwise trigger a hydration mismatch warning
- `THEME_SCRIPT` must be the first `