Hydration failed after adding next-themes dark mode
Hydration failed error after wrapping the app in ThemeProviderShort answer
next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ. Add suppressHydrationWarning to the html tag, render anything that reads the theme only after mount, and make the provider attribute match your Tailwind dark mode setting.
Fix it fast
1Find out which cause you have
Open the console and read the diff React prints. If the mismatch is on the html element, the cause is the first one; if it is inside your toggle button, the second.
grep -rn "useTheme\|ThemeProvider" app components2Match what you see, then jump to its fix
- 1
The mismatch names the <html> element, for example a class or style attribute that only the client hasThe html element has no suppressHydrationWarningFix - 2
The mismatch is inside your own component, such as an icon or a select that shows the current themeA component reads the theme during the first renderFix - 3
The page loads without errors but dark: classes never apply, or the theme flashes the wrong colour firstThe provider attribute does not match the Tailwind dark mode settingFix
- 1
What does the error look like?
Hydration failed error after wrapping the app in ThemeProviderConsole reports a server and client mismatch on the html element
Cause 1 of 3
The html element has no suppressHydrationWarning
1Check
next-themes updates the html element in the browser, so React sees different attributes than the server sent.
grep -n "<html" app/layout.tsx2Fix
Add suppressHydrationWarning to html and wrap children in the provider. The attribute only silences that one element, not its children.
// app/layout.tsx
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>
</body>
</html>3Verify
Hard reload the page with the console open; the html mismatch should be gone.
npm run devConfirmed by github.com
Cause 2 of 3
A component reads the theme during the first render
1Check
The theme is not known on the server, so useTheme() gives a different value on the client's first render than the server had. Find components that print theme.
grep -rn "useTheme()" app components2Fix
Track a mounted flag that flips in an effect and render theme-dependent output only after it is true. Render a same-size placeholder before that to avoid layout shift.
'use client'
import { useEffect, useState } from 'react'
import { useTheme } from 'next-themes'
export function ThemeToggle() {
const [mounted, setMounted] = useState(false)
const { theme, setTheme } = useTheme()
useEffect(() => setMounted(true), [])
if (!mounted) return <button aria-label="Theme" className="size-9" />
return (
<button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
{theme}
</button>
)
}3Verify
Reload and toggle the theme; the console should stay clean.
npm run devConfirmed by react.dev
Cause 3 of 3
The provider attribute does not match the Tailwind dark mode setting
1Check
Tailwind needs the provider to write a class when darkMode is the class or selector strategy.
grep -rn "attribute=" app components2Fix
Use attribute="class" on ThemeProvider and set darkMode to 'selector' in tailwind.config.js (use 'class' for Tailwind below 3.4.1).
// tailwind.config.js
module.exports = {
darkMode: 'selector',
}3Verify
Toggle the theme and check that the html element gains or loses the dark class.
# DevTools > Elements: look for class="dark" on <html>Confirmed by github.com
How do I stop it coming back?
- Keep ThemeProvider in one client component and import it into the root layout.
- Never print or branch on theme in a component without the mounted guard.
- Use suppressHydrationWarning only on html; it is an escape hatch and works one level deep.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
React hydration failed: the server HTML and the first browser render differ
Text content does not match server-rendered HTML
Hydration fails when the first render in the browser produces different HTML from the HTML the server sent.
5 causes, each with a fixWeb apps
Tailwind dark mode toggled with a class has no effect
dark: classes do nothing when the html element has class dark
By default dark: follows the operating system setting.
4 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
A shadcn/ui Dialog stays open after the form is submitted
Form submits and the data saves, but the modal remains on screen
A shadcn Dialog is a Radix dialog.
3 causes, each with a fixWeb apps
A Tailwind class does not override the class before it
A utility you added last has no effect on the element
Tailwind does not read your class attribute from left to right.
4 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fix