Hydration

Updated September 30, 20262 min read

In short

Hydration is the step where JavaScript in the browser takes over server-rendered HTML, attaching event handlers and state so the page becomes interactive.

What is hydration?

When a page is rendered with SSR or SSG, the browser receives complete HTML that it can display right away, but that HTML is inert: buttons and forms have no JavaScript behavior yet. Hydration is the step where the framework's JavaScript loads, rebuilds its picture of the components in memory, matches it to the existing HTML, and attaches event listeners and state.

Hydration is not the same as client-side rendering. CSR builds the page in the browser from an empty shell, while hydration reuses HTML that already exists and only adds interactivity. In React, for example, hydrateRoot() is used instead of createRoot() so the server's HTML is kept rather than thrown away and rebuilt.

Think of a stage set that is fully built before the audience arrives; hydration is the moment the actors walk on and the props start working. Until hydration finishes, the page can look ready but ignore clicks, and large JavaScript bundles make that gap longer, especially on slower phones. This delay often shows up in responsiveness metrics such as Interaction to Next Paint (INP).

A common problem is a hydration mismatch, which happens when the first render in the browser produces different markup than the server sent, for example because the code uses the current time, random values, or browser-only APIs while rendering. Techniques such as partial hydration, islands architecture, and React Server Components reduce the cost by hydrating only the parts of a page that need to be interactive.

Key takeaways

Hydration makes server-rendered or static HTML interactive.
The framework attaches event handlers and state to existing HTML.
Until hydration finishes, the page can look ready but not respond.
A hydration mismatch occurs when browser and server output differ.
Partial hydration and islands send less JavaScript to the browser.

Example

Hydrating server-rendered HTML in Reactjsx

// client.jsx: runs in the browser after the server's HTML has loaded
import { hydrateRoot } from "react-dom/client";
import App from "./App";

// Reuse the existing HTML inside #root and attach event handlers,
// instead of rendering the whole page again from scratch
hydrateRoot(document.getElementById("root"), <App />);

Readers ask

What is a hydration error?

A hydration error, or mismatch, happens when the first render in the browser produces different markup than the server sent. Common causes are dates, random numbers, and checks like typeof window during rendering; move such code into effects or event handlers that run after hydration.

What is the difference between hydration and client-side rendering?

Client-side rendering builds the page's HTML in the browser from an almost empty document. Hydration starts from HTML that the server already rendered and only attaches the JavaScript behavior.

What is partial hydration?

Partial hydration, often implemented as an islands architecture, hydrates only the interactive parts of a page, such as a search box or an image carousel, and leaves the rest as static HTML. This reduces the JavaScript the browser must download and run.