1# Hydration Errors
2 
3Diagnose and fix React hydration mismatch errors.
4 
5## Error Signs
6 
7- "Hydration failed because the initial UI does not match"
8- "Text content does not match server-rendered HTML"
9 
10## Debugging
11 
12In development, click the hydration error to see the server/client diff.
13 
14## Common Causes and Fixes
15 
16### Browser-only APIs
17 
18```tsx
19// Bad: Causes mismatch - window doesn't exist on server
20<div>{window.innerWidth}</div>
21 
22// Good: Use client component with mounted check
23'use client'
24import { useState, useEffect } from 'react'
25 
26export function ClientOnly({ children }: { children: React.ReactNode }) {
27  const [mounted, setMounted] = useState(false)
28  useEffect(() => setMounted(true), [])
29  return mounted ? children : null
30}
31```
32 
33### Date/Time Rendering
34 
35Server and client may be in different timezones:
36 
37```tsx
38// Bad: Causes mismatch
39<span>{new Date().toLocaleString()}</span>
40 
41// Good: Render on client only
42'use client'
43const [time, setTime] = useState<string>()
44useEffect(() => setTime(new Date().toLocaleString()), [])
45```
46 
47### Random Values or IDs
48 
49```tsx
50// Bad: Random values differ between server and client
51<div id={Math.random().toString()}>
52 
53// Good: Use useId hook
54import { useId } from 'react'
55 
56function Input() {
57  const id = useId()
58  return <input id={id} />
59}
60```
61 
62### Invalid HTML Nesting
63 
64```tsx
65// Bad: Invalid - div inside p
66<p><div>Content</div></p>
67 
68// Bad: Invalid - p inside p
69<p><p>Nested</p></p>
70 
71// Good: Valid nesting
72<div><p>Content</p></div>
73```
74 
75### Third-party Scripts
76 
77Scripts that modify DOM during hydration.
78 
79```tsx
80// Good: Use next/script with afterInteractive
81import Script from 'next/script'
82 
83export default function Page() {
84  return (
85    <Script
86      src="https://example.com/script.js"
87      strategy="afterInteractive"
88    />
89  )
90}
91```
92