LLM Best Practices

Hydration Mismatch

2 min read

View markdown source

Overview

This page is the atomic definition. The hydration lifecycle is described at hydration.

Definition

A hydration mismatch occurs when React’s client-side render of a component tree produces different HTML than the server sent. React compares its virtual tree against the actual DOM nodes. If they differ, React logs a warning (or in React 18, throws an error in strict mode) and falls back to a full client-side re-render of the mismatched subtree, discarding the server HTML. This defeats the performance benefit of ssr for affected components. Common causes: accessing window, navigator, or localStorage during render (these are undefined on the server); using Date.now() or Math.random() without a stable seed; rendering different markup based on authentication state that is only known client-side; browser extensions injecting DOM nodes; and locale or timezone differences between server and client. The fix is to defer environment-dependent logic to useEffect (which runs only on the client) or to use suppressHydrationWarning on elements whose content intentionally differs (such as timestamps). React Server Components (server-component) eliminate mismatch risk for their own output because they never hydrate.

When it applies

Hydration mismatches appear in any Next.js or React application using ssr or ssg with client-side hydration. They do not apply to pure csr apps or to React Server Components.

Example

// Causes mismatch: renders different HTML on server vs client
function Clock() {
  return <time>{new Date().toLocaleTimeString()}</time>;
}
 
// Fixed: defer to client with useEffect
function Clock() {
  const [time, setTime] = useState("");
  useEffect(() => setTime(new Date().toLocaleTimeString()), []);
  return <time>{time}</time>;
}
  • hydration - the process that mismatches disrupt.
  • ssr - SSR pages are the primary site of hydration mismatches.
  • react - React 18 throws errors in strict mode for most mismatch types.
  • nextjs - Next.js surfaces mismatch errors in the browser console and development overlay.
  • server-component - Server Components avoid mismatches by never running on the client.

Citing this term

See Hydration Mismatch (llmbestpractices.com/glossary/hydration-mismatch).

Graph View

Backlinks