Hydration Error in Next.js 13/14 - Complete Fix

The Error

Error: Hydration failed because the initial UI does not match what was rendered on the server.

Why This Happens

Hydration errors occur when React's client-side render doesn't match the server-side render. Common causes include different data on server vs. client, browser-only APIs, or mismatched HTML structure.

5 Solutions

1. Use Client-Only Rendering with useEffect

'use client'
import { useState, useEffect } from 'react'

export default function Component() {
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
  }, [])

  if (!mounted) return null

  return <div>{/* Your browser-only content */}</div>
}

2. Disable SSR for Specific Components

import dynamic from 'next/dynamic'

const NoSSRComponent = dynamic(
  () => import('./BrowserOnlyComponent'),
  { ssr: false }
)

export default function Page() {
  return <NoSSRComponent />
}

3. Suppress Hydration Warning (Use Carefully)

<div suppressHydrationWarning>
  {typeof window !== 'undefined' && <BrowserOnlyContent />}
</div>

4. Use localStorage Correctly

const [value, setValue] = useState('')

useEffect(() => {
  setValue(localStorage.getItem('key') || '')
}, [])

5. Ensure Consistent HTML Structure

Never nest block elements inside inline elements:

// ❌ Wrong
<p><div>Content</div></p>

// ✅ Correct
<div><p>Content</p></div>

Quick Fix Checklist

• Check for browser-only APIs (window, localStorage, document)
• Verify HTML structure is valid
• Use useEffect for client-only logic
• Consider dynamic imports with ssr: false
• Check for date/time mismatches between server and client