Basics

What Is Hydration — and Why the Page Is Visible but the Buttons Don't Work Yet

Illustration: a page layout stands complete while wires are still being pulled to its buttons

A familiar scene: the page opens, everything is drawn, you press a button — nothing. You press again. A second later it fires twice.

You're not slow and your connection is fine. You landed in the hydration window — the gap where the picture of the page exists but the wiring behind it doesn't. It's counterintuitive: we assume "visible" and "working" arrive together. They arrive separately, and there's a seam between them.

What hydration is, in one line

The server sends the browser finished HTML — text, headings, images, buttons. A person sees the page almost immediately, before a single line of JavaScript has loaded.

But that HTML is dead. The button is drawn; what it should do when pressed isn't written in it. The logic lives separately, in a JavaScript file.

Hydration is the moment the downloaded JavaScript finds the already-drawn elements and attaches itself to them, taking over. The React docs put it plainly: hydration turns the initial HTML snapshot from the server into a fully interactive app.

Simple analogy: the server delivered a finished apartment with switches on the walls. Hydration is the electrician running wire to them. Until they arrive, the switches exist but the lights don't turn on.

Where the "dead window" comes from

Between "visible" and "working", the browser has to:

  1. Download the JavaScript bundle (usually many times heavier than the HTML itself).
  2. Parse and execute it — that's CPU work, not network work.
  3. Walk the element tree and attach the handlers.

On your laptop this takes milliseconds and goes unnoticed. On a five-year-old budget phone, step 2 stretches out and the window becomes a real pause. Hence the paradox: the more code you added "for convenience", the longer the page stays a picture.

That window is exactly what ruins INP — "how long from the tap until the screen changes". More on it in the Core Web Vitals breakdown.

Worst of all, the window is invisible to the visitor: the page looks completely ready. There's no default indicator saying "hold on, still connecting."

Mismatch errors — and why you can't ignore them

Second surprise. To attach to the elements, the JavaScript must render exactly the same thing the server sent. If the result differs by one character, that's a hydration mismatch.

The React docs are blunt: the rendered content is expected to be identical to the server-rendered content, and mismatches should be treated as bugs and fixed. And then the interesting part — React does not validate all the markup: the docs say checking everything would be prohibitively expensive, so there are no guarantees that attribute differences get patched up. Mismatched text it won't try to patch at all.

Which means some discrepancies simply stay in your page and quietly break behaviour.

The classic causes, per the docs themselves:

  • Extra whitespace around the markup React generates.
  • Checks like "do we have a browser window" right inside rendering.
  • Reaching for browser-only APIs where the server has none.
  • Different data on server and client — current time, a random number, a locale-specific date.

That last one is the most common. The server rendered "14:03", the browser rendered "14:04" a second later, and everything drifted apart.

What to do in practice

  • Don't render "now" straight into the markup. Render a placeholder and fill in live time after the component has mounted.
  • Don't depend on screen size while rendering. The server doesn't know the window width and will always guess wrong.
  • Read the console error instead of silencing it. React has a targeted way to suppress the warning for cases like a timestamp, but it's a one-level escape hatch, not a fix.
  • Less code, smaller window. A static block — text, an image, a footer — needs no JavaScript at all. The most reliable hydration optimisation is not hydrating things nobody clicks.

Is hydration a React-only thing?

No. Any framework that renders HTML on the server and adds interactivity in the browser works this way — React, Vue, Svelte and the meta-frameworks on top of them. One word, one mechanism: markup first, then wires to the DOM.

How do I know I have a dead window?

Open the site on a phone and try pressing a button the instant you see it. If the first press gets swallowed, the window is there. Second method: turn on 4× CPU throttling in devtools and repeat.

Does hydration slow the site down?

It isn't free: the browser repeats part of the work the server already did. In exchange, a person sees content before the JavaScript arrives. Usually a good trade — but only while the bundle stays small.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →