Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Concepts and Pitfalls

Hydration

How React hydration turns server-rendered HTML into a live app: what React reuses, why mismatches happen, how to fix them and how Suspense helps.

Hydration is the step where React attaches itself to HTML that was already rendered on the server. The browser shows the server HTML immediately, then the JavaScript loads, hydrateRoot renders the same components on the client, and React connects them to the existing DOM nodes instead of creating new ones. It adds event handlers and starts effects; it does not rebuild the page.

For this to work, the first client render must produce exactly the same tree the server produced. If it does not, React reports a hydration mismatch, and may throw away the server HTML for part of the page and render on the client instead, which is slower and can cause flicker.

JSX
import { hydrateRoot } from 'react-dom/client';

hydrateRoot(document.getElementById('root'), <App />);

Try it

Reusing existing HTML

Click the button: it works, and the console reports that the original node was reused. Before hydration finished, the same button was visible but dead.

A mismatch and its recovery

With SAFE = false, the client's first render says yes while the server HTML says unknown. React logs the mismatch, reports it through onRecoverableError, and replaces the content by client rendering so the page ends up correct, at the cost of extra work. With SAFE = true the first render matches the server and the effect changes the text afterwards, with no error.

Why mismatches happen

Anything that makes the first render differ between server and browser:

  • Date.now(), new Date() or Math.random() used while rendering.
  • typeof window !== 'undefined' branches, localStorage, window.innerWidth and media queries read during render.
  • Locale or time-zone formatting that differs between machines.
  • Invalid HTML nesting (a <div> inside a <p>) that the browser parser repairs before React sees it.
  • Browser extensions or CDN features that modify HTML before React hydrates.
  • Different data on the server and the client for the same component.

How to fix them

  • Render the same thing first, then update. Keep client-only values in state that starts with a server-safe value and is updated in an effect.
  • Use useSyncExternalStore with a getServerSnapshot for values from the browser such as online status or the viewport.
  • Use useId for ids that must agree; random ids will not.
  • Serialize data from the server into the page and use it for the first client render.
  • suppressHydrationWarning on a single element silences an expected one-level text difference such as a timestamp. It is an escape hatch, not a fix (see suppressHydrationWarning).
  • Render client-only widgets after mount with the state-and-effect pattern, or do not server-render them.

Selective hydration

With Suspense boundaries React hydrates parts of the page independently. Streamed content can arrive late, and a boundary hydrates when its code and HTML are ready. If the user clicks inside a not-yet-hydrated boundary, React raises that boundary's priority and hydrates it first, replaying the click. Code splitting with lazy lets large widgets load after the first paint.

Usage notes

  • Hydration and Server Components are different. Server Components do not hydrate (they have no client code); only Client Components do. See Server Components.
  • React 19 reports one error with a diff of expected and actual markup, instead of several separate messages.
  • Hand-written server HTML must match exactly. Real server output separates adjacent text nodes with <!-- --> comment markers; the demos above build each text as one string so the pretend HTML can be a plain string.
  • Text mismatches recover less gracefully than you would hope. Treat any hydration warning as a bug to fix.
  • Effects never run on the server, so work done in them is always safe from mismatches.
  • Hydrate once. Calling hydrateRoot on a container that is already a root, or using the legacy hydrate, is an error in React 19.
  • Performance cost: hydration repeats the render work in the browser and must download the component code. Less client code means a faster interactive page.