Hydration

react internalsrenderingmediumhybrid~6 min

Slap yourself if

You think hydration just means React attaching event listeners.

Why this exists

Hydration exists to make server-rendered HTML interactive without re-creating the DOM, preserving performance benefits of SSR while enabling client-side behavior.

Mental model

Hydration is React replaying the render process on the client and matching it node-for-node with existing server-generated HTML. If the structure matches exactly, React attaches behavior without touching the DOM.

  • The browser parses HTML received from the server.
  • The DOM is constructed and painted before JavaScript executes.
  • React runs on the client and generates its expected virtual tree.
  • React compares the expected output with the existing DOM.
  • If everything matches, React attaches event handlers without recreating nodes.
  • Using non-deterministic values like Date.now() or Math.random() during render.
  • Conditional rendering that differs between server and client.
  • Accessing browser-only APIs during server rendering.
  • Locale or timezone differences causing text mismatches.

Hydration is the process where React reconciles an existing server-rendered DOM with its virtual tree on the client, attaching interactivity without recreating DOM nodes if the markup matches exactly.

  • Hydration just turns SSR into CSR.
  • Hydration is only about event listeners.
  • Hydration always improves performance.

Deep dive

Requires Pro

Premium deep dives include more internals, more scars.

React Fiber hydration path

Hydration is not a single step. It’s a Fiber traversal that can bail out to client rendering when mismatches occur.
  • Where hydration work is scheduled
  • How React decides a node can be reused
  • Where mismatches trigger fallback behavior

Mismatch detection and bailout behavior

A mismatch isn’t just a warning—it can throw away SSR benefits for a whole subtree.

Related terms

Streaming SSR

You think streaming SSR is just 'SSR but faster' or only about sending HTML in chunks.

renderingperformancehard

Partial Hydration

You think partial hydration just means hydrating components later.

react internalsrenderinghard

Concurrent Rendering

You think concurrent rendering means React renders in parallel threads or it always makes apps faster.

react internalsrenderinghard

Suspense boundaries

You think Suspense is just a loading spinner with better ergonomics.

renderingconcurrencyhard

Server components

You think server components are just SSR with better DX or a way to hide API calls.

renderingserver renderinghard