Course contentsShow
← React
Lesson 1653 of 2,39640. Server-Side RenderingFree lesson

What is a Hydration Mismatch?

Understanding what happens when server-rendered HTML doesn't match the client's initial render output.

What is a Hydration Mismatch?

You'll learn: what happens when the server-rendered HTML doesn't match what React expects to render on the client, causing hydration to fail.

The Core Problem

A hydration mismatch occurs when the HTML structure React generates on the server differs from what it tries to generate on the client during hydration. Remember, hydration is the process where React attaches event listeners to server-rendered HTML—but it assumes the HTML is already correct. If the structures don't match, React encounters an error.

Think of it like a puzzle: the server sends you a completed puzzle (the HTML), and the client tries to label each piece (hydrate). If the pieces don't match what the client expects, the client can't properly attach the labels.

Common Causes

Time-dependent data: Rendering new Date().toLocaleString() on the server produces one time, but by the time the client hydrates, it's a different time.

Random values: Using Math.random() generates different values on server and client.

Browser-only APIs: Checking window.innerWidth on the client when it didn't exist on the server.

Conditional rendering based on environment: Showing different content based on typeof window !== 'undefined'.

What Happens

React detects the mismatch and logs a warning. It then tries to recover by forcing a client-side re-render, but this defeats the purpose of SSR—you lose the performance benefit and get a flash of incorrect content.

Key Takeaway: A hydration mismatch happens when server and client render different output for the same component, breaking React's assumption that the initial HTML matches—avoid time-dependent, random, or browser-specific values in your initial render to prevent mismatches.