Hydration: matching the server's HTML, and paying for the JS you ship

What hydration actually does

Server-rendered HTML is paint, not behavior: the user sees a complete page, but no listener is attached, no state exists, refs are empty. Hydration is how React brings it to life: hydrateRoot(domNode, reactNode) renders the component tree again on the client — but instead of creating DOM, it walks the existing server-produced DOM, adopts each node into its fiber tree, attaches event handlers, and initializes state and effects. It is a render whose output is reconciliation against markup that already exists.

This design has one hard precondition, stated bluntly in React’s docs: the React tree you pass to hydrateRoot must produce the same output the server produced. React does not diff-and-patch differences during hydration; matching is an assumption baked into the algorithm, not a feature it provides. Text content differences get patched in development with a warning, but structural or attribute mismatches in React 18 trigger recovery: React abandons the server HTML for the affected boundary and performs a full client-side render to replace it. The user-visible cost is a flash of replaced content; the performance cost is that your mid-range-device user just rendered the page twice — once in HTML they couldn’t interact with, once in JS that blocked the main thread.

// The three classic mismatch factories — all are "two honest renders, two answers":

// 1. Time: server renders at T0, client hydrates at T0 + network + parse + execute.
<span>{formatRelative(order.createdAt, Date.now())}</span>

// 2. Locale/environment: Node's ICU vs the user's browser settings.
<td>{price.toLocaleString()}</td>

// 3. Browser-only branches: there is no window during the server render.
<div>{typeof window !== "undefined" ? <LocalStorageGreeting /> : <DefaultGreeting />}</div>

// The fix shape is always the same: first client render must equal the server render.
function ClientOnly({ children }: { children: React.ReactNode }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);   // effects run only after hydration
  return mounted ? <>{children}</> : null; // both server and first client render: null
}

The fix pattern deserves emphasis because it looks paradoxical: to render browser-dependent content, you render nothing (or a placeholder) on both the server and the first client pass, then switch after useEffect fires — effects only run post-hydration, so the switch is an ordinary update, not a mismatch. For a single unavoidable divergence (a timestamp the server must render), suppressHydrationWarning on that element tells React to leave that one text difference alone — a scalpel, not a policy. Random IDs are solved properly with useId, which is hydration-stable by construction.

Selective hydration: Suspense as a hydration boundary

Before React 18, hydration was monolithic: one synchronous pass over the whole tree, and nothing was interactive until everything was. The page couldn’t even begin hydrating until all its JS arrived, and a heavy component high in the tree held every sibling hostage. React 18’s selective hydration breaks the monolith using <Suspense>: each Suspense boundary becomes an independently hydratable island. Hydration proceeds boundary by boundary, in chunks that yield to the main thread — and it is priority-driven: if the user clicks inside a not-yet-hydrated boundary, React records the event and synchronously hydrates that boundary first, jumping the queue, then replays the interaction. The heavy comments widget at the bottom no longer delays the buy button at the top.

This composes with streaming SSR: a server component that suspends (slow data) streams its HTML later, and hydrates when it arrives, while the shell is already interactive. The mental model shifts from “the page hydrates” to “boundaries hydrate, in the order users need them.”

export default function ProductPage() {
  return (
    <main>
      <BuyBox />                       {/* critical: hydrates first */}
      <Suspense fallback={<Skeleton />}>
        <Reviews />                    {/* heavy: streams + hydrates later */}
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <Recommendations />            {/* user clicks here? -> queue-jumps */}
      </Suspense>
    </main>
  );
}

A second property matters operationally: in React 18, a hydration mismatch inside a Suspense boundary recovers at that boundary alone — the client re-render is scoped to the island instead of cascading to the root. Boundaries are blast-radius walls for mismatch recovery, not just loading states.

Islands, INP, and the JS you didn’t ship

Before you optimize how fast your app hydrates, ask a more useful question: how much of what you’re hydrating actually needs to run in the browser? The answer, in most apps, is far less than what’s currently shipping.

Hydration cost is roughly proportional to the JS you ship: every shipped component must be downloaded, parsed, executed, and reconciled against the DOM before it’s truly interactive. That work lands on the main thread and shows up in two field metrics. TBT (Total Blocking Time, lab) accumulates every long-task slice over 50ms during load — monolithic hydration of a big tree is exactly such a task, often 1–3 seconds of blocking on a mid-range Android device for a few hundred KB of components. INP (Interaction to Next Paint, a Core Web Vital) measures real interaction latency; the threshold for “good” is 200ms, and a tap that lands mid-hydration waits for the main thread before anything paints. The page looks ready — HTML painted seconds ago — but pokes like a dead thing: that gap between painted and interactive is precisely the hydration window, and users spend it rage-clicking.

The architectural response across the ecosystem is islands of interactivity: server-render everything, hydrate only the components that genuinely need JS. Next.js expresses islands through the RSC boundary — server components ship zero JS and never hydrate; only "use client" subtrees do. Astro expresses it as per-island directives; Qwik goes further and resumes serialized state instead of replaying renders. The engineering lever is the same everywhere and it’s the one you control directly: the fastest hydration is the hydration you don’t ship. Moving a formatter, a static chart, or a markdown body from a client component to a server component doesn’t make hydration faster — it makes that subtree’s hydration cease to exist, and TBT/INP improve in direct proportion.