What is Hydration, and what commonly causes a Hydration Mismatch?

Short answer

Hydration connects JavaScript event handlers to server-rendered HTML; a Mismatch occurs when the server-generated tree differs from the tree the client wants to create.

Explanation

After receiving SSR HTML, React matches existing DOM elements against the client's render output. If they differ (for example, due to Date.now(), window, or invalid HTML such as a <p> inside a <p>), matching fails. React may discard the old tree and rebuild it, showing a warning.

Code example

// Common cause of Mismatch: relying on a changing date on the server and client
function Timestamp() {
  // Error: the server and client have different times
  // return <span>{new Date().toLocaleTimeString()}</span>;

  // Correct solution: display the time only after mount in the browser
  const [time, setTime] = useState<string | null>(null);
  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
  }, []);

  return <span>{time || "Loading..."}</span>;
}

Common mistakes

• Hiding the warning everywhere with suppressHydrationWarning instead of fixing the mismatch.

Follow-up questions

• What is Islands Architecture, and how does it compare with traditional React Hydration?
• What is useId, and why is it needed to create unique, accessible IDs in SSR?

Sources

• React docs — hydrateRoot