- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
next-themes is the canonical way to wire dark mode in Next.js. It handles persistence, system preference, and the FOUC (flash of unstyled content) that follows a manual localStorage read.
Prerequisites
- Next.js 15 or newer (App Router)
- React 19
- Frakment theme block already in
globals.css
Install next-themes
$ bun add next-themes$ npm install next-themes$ pnpm add next-themes$ yarn add next-themes
Create the provider
"use client"
import { ThemeProvider as NextThemesProvider } from "next-themes"
import type * as React from "react"
export function ThemeProvider(
props: React.ComponentProps<typeof NextThemesProvider>
) {
return <NextThemesProvider {...props} />
}Wrap the root layout
import { ThemeProvider } from "@/components/site/theme-provider"
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider
attribute="class"
defaultTheme="system"
enableSystem
disableTransitionOnChange
>
{children}
</ThemeProvider>
</body>
</html>
)
}suppressHydrationWarning on <html> is required. next-themes sets the class attribute before React hydrates, which causes a mismatch warning without it.
Add a toggle
"use client"
import { MoonIcon, SunIcon } from "lucide-react"
import { useTheme } from "next-themes"
import * as React from "react"
import { Button } from "@/components/ui/button"
export function ModeToggle() {
const { resolvedTheme, setTheme } = useTheme()
const [mounted, setMounted] = React.useState(false)
React.useEffect(() => setMounted(true), [])
if (!mounted) {
return <Button variant="ghost" size="icon" aria-label="Toggle theme" />
}
const isDark = resolvedTheme === "dark"
return (
<Button
variant="ghost"
size="icon"
aria-label="Toggle theme"
onClick={() => setTheme(isDark ? "light" : "dark")}
>
{isDark ? <SunIcon /> : <MoonIcon />}
</Button>
)
}The mounted guard prevents a hydration mismatch. Before mount, resolvedTheme is undefined, so render a neutral button.
Prevent the flash
next-themes injects a blocking script into <head> that reads localStorage and applies the class before the first paint. No extra setup needed.
If you see a flash anyway:
- Do not call
setThemeduring SSR. Only from event handlers or effects. - Keep
<html suppressHydrationWarning>. Removing it triggers a mismatch. - Do not render theme-dependent UI without the
mountedguard. The server has no access tolocalStorage.
Per-section override
Force a subtree to stay light or dark:
<div className="light">{/* always light */}</div>
<div className="dark">{/* always dark */}</div>Troubleshooting
Remove the disableTransitionOnChange prop if the flash is a color transition, not a class swap. If the flash is white-to-dark, next-themes is not injected in <head>. Check that ThemeProvider wraps <html> children, not a nested element.
Add suppressHydrationWarning to <html>. next-themes sets the class attribute outside of React, so React treats the mismatch as an error without this prop.
The theme block is missing from globals.css, or .dark tokens are not defined. Run npx frakment init again.
Next
- Theming - token reference
- Vite dark mode - SPA setup
- next-themes docs - upstream reference