Hydration assumes the client's first render matches the server HTML. A mismatch is any difference; React 19's development build reports it with a diff.
Common causes:
- Branching on the environment in render:
typeof window,localStorage,matchMedia. - Values that change between renders:
Date.now(),Math.random(), a date formatted in the server's time zone or locale. - Different data: the client fetched newer data instead of reusing the server's.
- Invalid nesting: the server sends
<p><div>, the HTML parser closes the<p>, and the DOM no longer matches the tree. - Nodes injected by extensions, or whitespace around the HTML inside the root container.
What React does (React 19.3.1, measured):
- Different tag or text: hydration fails at that point. React reports a recoverable error ("Hydration failed because the server rendered text didn't match the client…"), discards the server DOM up to the nearest
<Suspense>boundary, or the whole root without one, and renders it on the client.onRecoverableErrorreceives it. - Different attribute: only a development
console.error("…This won't be patched up."). The DOM keeps the server's value, which the docs allow: attribute fixes aren't guaranteed.
Fixes, best first:
- Make the render deterministic: pass the server's data and timestamps to the client, format dates with an explicit
timeZone, fix the markup, and generate ids withuseId, which derives them from tree position. - For content that can only exist in the browser, render a placeholder first. Either set a flag in
useEffectand render a second pass, or, since React 19.3, calluse(browser())fromreact-dominside a<Suspense>boundary: the server sends the fallback and the client renders the content. - For one unavoidable difference, such as a timestamp, put
suppressHydrationWarningon that element. It covers only that element's own text and attributes, and React won't patch them.