Suggest an edit

Improve this article

Refine the answer for “What is hydration in the context of SSR?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What hydration is

**Hydration** is the process where **client-side JavaScript "brings to life" HTML that was already rendered on the server**, adding interactivity (event handlers, state, reactivity, etc.).

In other words:

> SSR creates **ready-made HTML**, and **hydration** turns that HTML into a **real React app** on the client.

---

## How the process works step by step

1. The **server** generates a ready HTML page (via `renderToString()` or `renderToPipeableStream()`):

```javascript
  <div id="root">
    <button>Click me</button>
  </div>
  ```
2. The **browser receives the HTML** and shows it to the user right away - the page is already visible, but **not yet interactive** (clicking the button does nothing).
3. The **JS bundle loads** and runs on the client.
React renders the same component again (virtually) and **matches** it against the existing HTML.
4. If the structure matches, React **attaches event handlers** and activates component state, making the page "alive".
This is **hydration**.

---

## An analogy

Imagine SSR creates a "statue" (ready-made HTML),
and hydration "breathes life into it" (adds JS behavior).

---

## Example in React

```javascript
// Server
import { renderToString } from 'react-dom/server';
const html = renderToString(<App />);
res.send(`<div id="root">${html}</div>`);

// Client
import { hydrateRoot } from 'react-dom/client';
hydrateRoot(document.getElementById('root'), <App />);
```

- The server creates the HTML (`renderToString`).
- The client calls `hydrateRoot()` to **attach React logic** to the already-ready DOM.

---

## Why this matters

Hydration lets:

- the user **see content right away** (SSR rendering),
- while still getting **interactivity** (React's client-side logic).

Without hydration, an SSR page would be just static HTML - "mute" and "dead".

---

## Problems related to hydration

### 1. **HTML mismatch**

If the server HTML doesn't match the client HTML, React shows an error:

> `Hydration failed because the initial UI does not match what was rendered on the server.`

Causes:

- using `Math.random()`, `Date.now()`, etc.;
- conditional rendering that depends on `window`, `localStorage`, `navigator`, etc.;
- a difference in data between the server and the client.

---

### 2. **A long hydration process**

Hydration requires **walking the entire DOM again** and binding events.
On large pages this can take **hundreds of milliseconds** -> the UI "hangs" without responding.

The solution is **partial / selective hydration** (hydrating by chunks or by event).

---

### 3. **Delayed interactivity**

Until hydration finishes, buttons and forms may be inactive.
That's why modern frameworks (Next.js, React 18, Qwik, Astro) use:

- **Streaming SSR** - HTML arrives in parts and renders immediately.
- **Partial Hydration** - only the necessary sections are activated.
- **Resumability (Qwik)** - avoids hydration altogether.

---

## Comparing page states

| Stage | What the user sees | What's happening |
|---|---|---|
| SSR render | Content displayed | HTML from the server, no JS |
| Hydration | Content displayed | React attaches JS logic |
| After hydration | Content is interactive | A full SPA is running |

---

## Conclusion

**Hydration is the bridge between server rendering and client-side interactivity.**

- SSR makes HTML visible instantly.
- Hydration "brings this HTML to life" by adding React behavior.
- Hydration errors and delays are one of the main technical challenges of SSR architectures.

Markdown · drag & drop images · ⌘B / ⌘I shortcuts526 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.