Next.jshard

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

Answer

It happens when the server-rendered HTML differs from the client’s first render (e.g., `Math.random()`, `Date.now()`, `window` branches, locale formatting). Fix by making initial render deterministic or moving client-only values to `useEffect`/client components.

Advanced answer

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