Skip to main content
Software Dictionary

Hydration

Updated 2 min read

Share this page

Send the link, quote the definition with a link back, or show it as a card on your own site.

https://softwaredictionary.org/terms/hydration

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.

At a glance

Hydration: the server sends ready HTML, the JavaScript bundle loads, React attaches event handlers to that HTML, and the page becomes interactive.1234Ready HTMLfrom the serverJS bundledownloads and runsHydrationattach handlersInteractivepage respondsvisible, but clicks do nothingclicks work
Hydration reuses the HTML already on screen and only adds the behavior.

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.

Free ยท once a week

Software and AI, explained once a week

The week's software and AI news with every term explained, plus a term to learn and a quick quiz. A two-minute read.

You confirm by email first, and one click unsubscribes. Privacy

See this week's issue

About this page

Spotted a mistake or something missing on this page?Suggest an edit

How pages are made

More

Settings