Hydration

Hydration is the step where JavaScript running in the browser attaches event handlers to already-rendered HTML, turning a static-looking page into a working application. It gets its own glossary entry because the gap between "looks ready" and "actually responds to a tap" is where slow, janky pages live, and where a chunk of your Interaction to Next Paint budget quietly disappears.

The framework ships HTML that was produced on the server or at build time (see pre-rendering), the browser paints it fast, and then the framework loads its bundle, walks the existing markup, matches it to its component tree, and wires up the click handlers. Until that finishes, the buttons are painted but dead. That is the whole story, and also the whole problem.

What hydration actually does, step by step

Here is a stripped-down React example. The server sends real HTML for the counter, then hydrateRoot adopts that markup instead of throwing it away and rebuilding:

// Server sent this HTML already:
// <div id="root"><button>Liked 0 times</button></div>

import { hydrateRoot } from 'react-dom/client';
import App from './App';

// Do NOT use createRoot here, that would discard the
// server HTML and re-render from scratch (flash + wasted work).
hydrateRoot(document.getElementById('root'), <App />);

Before that line runs, the button is visible and readable. A crawler that never runs the script still sees "Liked 0 times." A human who taps it before hydration finishes gets nothing, then a delayed reaction once the handler attaches. Multiply that by a heavy bundle on a mid-range Android phone and you understand why hydration is a performance topic, not a trivia topic.

Full hydration vs. the alternatives

"Just hydrate the whole page" is the default, and it is also the most expensive option. The strategies below trade complexity for a smaller JavaScript-on-main-thread bill.

How to check hydration on your own site

1. View the raw HTML first. Run curl -sL https://yoursite.com/page | grep -o "your headline text". If your main content shows up, it survived without JavaScript. If the body is an empty <div id="root"></div>, hydration is delivering content, not just interactivity, and crawlers may miss it.
2. Use the URL Inspection tool in Search Console. Look at the rendered HTML and screenshot. If Google's Web Rendering Service shows your content, the second wave caught it, but you are relying on the render queue.
3. Throttle the CPU in Chrome DevTools. Performance panel, set CPU to 4x or 6x slowdown, reload, and record. The gap between First Contentful Paint and the moment handlers respond is your hydration cost.
4. Measure INP with real users. Pull the field data from CrUX or a RUM tool. A p75 above 200ms on interactive pages usually points at hydration blocking the main thread.
5. Tap something the instant it paints. On a real phone, reload and mash a button immediately. If nothing happens for a beat, that dead window is exactly what your slowest users feel.

Common mistakes and how to fix them

• Content that only exists after hydration. If the served HTML is empty and the text appears only once React/Vue mounts, you have handed indexing over to the render queue. Fix: server-render or pre-render the actual content so it is in the HTML on arrival.
• Hydration mismatch warnings ignored. When server HTML and client render disagree (a date rendered with the server's timezone, say), the framework may throw away the markup and re-render, doubling the work. Fix: read the console warning, make server and client output identical, gate client-only values behind a mount effect.
• One giant bundle hydrating everything. A blog post does not need the checkout widget's JavaScript. Fix: code-split and move to island or progressive hydration so static content ships zero JS.
• Blocking hydration on third-party scripts. Chat widgets and tag managers fighting for the main thread stretch the dead window. Fix: defer non-critical third parties and load them after interaction is ready.
• Assuming hydration helps SEO. It does not add anything for crawlers; the pre-hydration HTML is what they read. Fix: judge hydration purely on interactivity and INP, and put your SEO effort into what is in the served markup.

Frequently asked questions

Related reading: JavaScript SEO: How Search Engines and AI Crawlers Render Your Pages, SSR vs CSR: Why Rendering Decides Whether AI Can Read Your Site, INP: Interaction to Next Paint.