# Hydration

Hydration attaches client-side application state and interaction behavior to HTML that was rendered before the browser application started.

- Type: term
- Domain: Engineering & architecture
- Level: Advanced
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/hydration/>)

## What it means

Hydration is the client process that activates server-rendered or pre-rendered HTML by reconciling it with application code, restoring state, and attaching behavior such as event handlers. It aims to reuse existing markup rather than discard and recreate it. Partial and selective approaches reduce how much of the page must hydrate.

## Why it matters

Hydration can combine early HTML with rich client interaction, but it often sends similar rendering logic and data twice and consumes main-thread time after content appears. Users may see controls before those controls can respond.

## When to use it

Use hydration when server or static HTML must become part of a stateful client application. Prefer native HTML, small enhancements, or selectively hydrated components when most content does not require a persistent client runtime.

## How it works

1. The server or build process renders HTML from application state.
2. The response carries the markup plus enough data and scripts to reproduce that state.
3. The browser displays the HTML while client code downloads and executes.
4. The client matches its component structure to the existing DOM and attaches behavior.
5. Mismatch handling and telemetry reveal inconsistent rendering or delayed interaction.

## A practical example

A news page renders article text and subscription controls on the server. The article remains plain HTML, while only the pricing selector and sign-up dialog hydrate when needed, reducing the period in which visible controls are inactive.

## Where it breaks

Hydration can duplicate work, increase JavaScript and serialized data, create mismatches between server and client output, and delay responsiveness. Framework behavior differs, so the label alone does not specify cost or scope.

## Common mistakes

- Assuming visible server-rendered controls are already interactive.
- Hydrating an entire page when only a few components need client state.
- Generating nondeterministic server and client markup that cannot reconcile.
- Measuring first paint while ignoring interaction delay and main-thread work.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/hydration/#visualization-hydration>)

## Sources

1. [Rendering on the Web](<https://web.dev/articles/rendering-on-the-web>) — web.dev · Official technical guidance
2. [hydrateRoot](<https://react.dev/reference/react-dom/client/hydrateRoot>) — React · Official framework documentation

## Related topics

- [Server-Side Rendering \(SSR\)](<https://wiki.soroush.uk/topic/server-side-rendering/>)
- [Client-Side Rendering \(CSR\)](<https://wiki.soroush.uk/topic/client-side-rendering/>)
- [Browser Event Loop](<https://wiki.soroush.uk/topic/browser-event-loop/>)
