Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Hydration failed after adding next-themes dark mode

ErrorHydration failed error after wrapping the app in ThemeProvider

Short 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.

  • Applies to Next.js 15, React 19, next-themes, Tailwind CSS 4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 components
  2. 2Match what you see, then jump to its fix

    1. 1The mismatch names the <html> element, for example a class or style attribute that only the client hasThe html element has no suppressHydrationWarningFix
    2. 2The 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. 3The 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

What does the error look like?

  • Hydration failed error after wrapping the app in ThemeProvider
  • Console 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.tsx

2Fix

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 dev

Confirmed by github.com

Did this fix it?

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 components

2Fix

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 dev

Confirmed by react.dev

Did this fix it?

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 components

2Fix

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

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.