Hydration: Definition, Process and Performance Cost

What is hydration?

Hydration is the step where JavaScript in the browser attaches to HTML that the server already rendered. The framework reuses the existing DOM, wires up event handlers and rebuilds component state, so a static-looking page becomes interactive. It is the second half of server-side rendering in frameworks such as React with Next.js. Its cost is a common reason a fast-looking page still responds slowly to taps and clicks.

How hydration works

1. The server renders the page to HTML and sends it, so the browser can paint content early.
2. The browser downloads, parses and runs the JavaScript bundle.
3. The framework runs the components again in the browser and matches them to the existing DOM nodes. In React this is hydrateRoot.
4. Event handlers and state are attached. From here on the page is interactive.

Between steps 1 and 4 the page looks ready but clicks may be ignored or delayed. That gap is the hydration cost, and it shows up in Interaction to Next Paint (INP). Google rates INP at the 75th percentile of real page loads: 200 ms or less is good, above 500 ms is poor (web.dev).

Example

A product page is server-rendered and paints in under a second. The framework bundle is large and a chat widget loads at the same time. A visitor on a mid-range phone taps "Add to cart" while hydration is still running on the main thread. The tap is queued and the button reacts a second or two later. The server HTML was fast; the hydration work behind it was not.

Why hydration is slow

• It re-runs the component tree in the browser, even for parts that never change.
• The bundle must download and parse first, so more JavaScript means a longer gap.
• It runs on the main thread, which also handles user input.
• It competes with images, third-party scripts and ads.
• It is device dependent. A phone can be several times slower than a development laptop.

Techniques that reduce hydration cost

• Ship less JavaScript. Code splitting and removing unused code shorten every step.
• Islands. Astro renders pages to plain HTML and adds JavaScript only to components marked with a client:* directive, and each island hydrates separately, for example on load, when idle or when visible (Astro docs).
• Streaming and Suspense. React's renderToPipeableStream sends the shell first and streams the rest as data arrives, so content appears before the scripts load (React docs).
• Server Components. Components that run only on the server need no client JavaScript of their own.
• Resumability. Qwik pauses execution on the server and resumes it in the browser instead of replaying application logic (Qwik docs).
• No hydration. Purely static pages from static site generation need no hydration, and lazy loading below-the-fold code keeps the first load light.

Common hydration mistakes

• Hydration mismatches. The client render must produce the same output as the server. Typical causes are timestamps and locale formatting, browser-only APIs such as window.matchMedia used during render, and typeof window checks in render logic. React treats mismatches as bugs: it can recover, but that may slow the app or attach handlers to the wrong elements (React docs).
• Fixing mismatches with a second render. Switching content in useEffect works, but components render twice and the UI can visibly change after load. suppressHydrationWarning is for single elements only.
• Hydrating everything. Content-only parts such as footers and article text rarely need JavaScript.
• Heavy state set-up at start-up and synchronous third-party scripts that delay interactivity.
• Testing only on a fast laptop. Hydration problems show on real mid-range phones.

Measuring hydration with monitoring

Hydration is invisible in a screenshot, so measure it. The free Core Web Vitals checker shows real-user LCP, INP and CLS from Chrome UX Report data, aggregated over 28 days. For lab data, page speed monitoring runs Lighthouse audits from 25 cloud regions, tracks Total Blocking Time (a lab metric that reflects main-thread work like hydration) and can alert you when a metric regresses. See also how to monitor Core Web Vitals with alerts and reports and mastering JavaScript for performance.

FAQ: Hydration

Why is hydration needed?

Server-rendered HTML is only markup. Hydration adds the JavaScript that makes it interactive, with event handlers, state and effects, without throwing away the HTML the user already sees.

What is the difference between rendering and hydration?

Rendering produces the HTML. Hydration attaches JavaScript to HTML that already exists. In SSR, rendering happens on the server first and hydration follows in the browser.

What is a hydration mismatch?

It happens when the HTML from the server differs from what the client renders for the first time, for example because of a timestamp or a browser-only value. React logs a warning and may have to redo work on the client.

Does hydration affect SEO?

Indirectly. Search engines can read the server HTML, but slow hydration hurts responsiveness and therefore INP, which is part of Core Web Vitals.

Can I avoid hydration completely?

Yes for pages without interaction, such as static content pages. For interactive pages you can limit it with islands, Server Components or a resumable framework like Qwik.

How do I know if hydration is hurting my site?

Check INP in field data and Total Blocking Time in a Lighthouse run, then profile the main thread on a mid-range phone to see long tasks right after load.