Frontend Beauty
ESC

Type to search the knowledge base.

Hydration Mismatches

Why server HTML must match the client’s first render: common causes, useId, dates, and suppressHydrationWarning.

advanced3 min read
  • react
  • hydration-mismatches

With SSR or RSC + client hydration, React attaches to existing HTML. If the client’s first render tree does not match the server markup, you get a hydration mismatch — warnings in dev, discarded server DOM, and potential UI glitches or security surprises.

Docs: hydrateRoot, useId.

Common causes

// Bad: different on server vs client
function Clock() {
  return <span>{new Date().toLocaleString()}</span>;
}

function RandomBadge() {
  return <span>{Math.random()}</span>;
}

function BrowserOnly() {
  return <span>{window.innerWidth}</span>; // window missing on server
}

Also: invalid HTML nesting (<p><div/></p>) that the browser “fixes” before React hydrates, extension-injected DOM, and locale/timezone differences.

Fixes

1. Same deterministic output for the first client render as the server.

2. Client-only after mount for inherently browser values:

function Width() {
  const [w, setW] = useState(null);
  useEffect(() => setW(window.innerWidth), []);
  if (w === null) return <span>—</span>; // server + first client paint
  return <span>{w}px</span>;
}

3. useId for ids instead of random counters.

4. suppressHydrationWarning only on specific text nodes you accept (e.g. timestamps) — not a blanket ignore on the app root:

<time suppressHydrationWarning>{new Date().toLocaleString()}</time>

Next.js notes

Client Components still SSR by default. "use client" does not mean “client only.” Use dynamic(..., { ssr: false }) sparingly for true browser-only widgets. Mismatches often come from localStorage reads during render.

Interview out-loud

“Hydration requires the client’s first render to match server HTML. I avoid Date.now, random, and window during render, use useId for ids, defer browser-only values to effects, and reserve suppressHydrationWarning for tiny intentional mismatches.”

Further reading

Edge cases worth rehearsing

Interviewers and production incidents cluster around the same edges: first render versus update, empty and loading states, Strict Mode double setup, concurrent interruptions, and what happens when identity (key, route params, user id) changes mid-edit. Walk one concrete user journey end-to-end — open, edit, navigate away, come back — and say which state survives.

Prefer fixing data flow and ownership before reaching for memoization or micro-optimizations. Prefer event handlers over effects when a user action is the trigger. Prefer deriving values during render over mirroring props into state. Prefer stable list keys from business ids. Measure with the profiler when performance is the claim.

When you cite an API, mention one failure mode: abort on unmount, serializable props across server/client boundaries, focus restoration for dialogs, or cache invalidation after a mutation. Specific beats generic every time.

Edge cases worth rehearsing

Interviewers and production incidents cluster around the same edges: first render versus update, empty and loading states, Strict Mode double setup, concurrent interruptions, and what happens when identity (key, route params, user id) changes mid-edit. Walk one concrete user journey end-to-end — open, edit, navigate away, come back — and say which state survives.

Prefer fixing data flow and ownership before reaching for memoization or micro-optimizations. Prefer event handlers over effects when a user action is the trigger. Prefer deriving values during render over mirroring props into state. Prefer stable list keys from business ids. Measure with the profiler when performance is the claim.

When you cite an API, mention one failure mode: abort on unmount, serializable props across server/client boundaries, focus restoration for dialogs, or cache invalidation after a mutation. Specific beats generic every time.

Related guides