What causes a hydration mismatch in React/Next.js and how do you fix it?

Deep dive

Hydration is React attaching event listeners and reconciling the server-rendered HTML with the first client render. A mismatch happens when the HTML generated on the server is not the same as what the client renders initially.

Common causes

• Non-deterministic values during render: `Math.random()`, `Date.now()`, `crypto.randomUUID()`.
• Browser-only branches: `typeof window !== 'undefined'` during render.
• Locale/timezone differences (date/number formatting).
• Client-only layout changes (measuring DOM, reading `localStorage`) happening during render.

Fix patterns

• Make the first render deterministic; move client-only reads to `useEffect`.
• Render placeholders on the server and fill on the client.
• If a widget is truly client-only, dynamically import it with SSR disabled.

Example

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

export function Clock() {
  const [now, setNow] = useState<string>('')
  useEffect(() => setNow(new Date().toISOString()), [])
  return <span>{now || '...'}</span>
}

Common pitfalls

• Using `suppressHydrationWarning` as a blanket fix (it hides bugs).
• Formatting dates without a fixed locale/timezone.
• Assuming the server and client environment are identical (they aren’t).