What is Hydration

How it works

The framework re-runs enough of the app in the browser to match the server HTML, then binds interactivity to it instead of rebuilding the DOM from scratch. Modern approaches reduce the cost of this step.

• Non-destructive hydration reuses server DOM instead of re-rendering it
• Incremental or partial hydration only hydrates parts that need interactivity
• Deferred hydration delays non-critical components until needed

Common mistakes

The most common bug is a mismatch between server and client HTML, which forces the framework to discard and rebuild the DOM, causing flicker and layout shift. Hydrating everything eagerly on large pages is another, since it blocks the main thread and delays interactivity.

Why it matters

Hydration is the step where JavaScript "wakes up" server-rendered HTML in the browser, attaching event listeners and state so the static markup becomes an interactive app. It matters because it is where the SEO/performance benefits of server rendering can be partly given back: the user sees content instantly (good), but the page is not actually interactive until the JavaScript downloads, parses and hydrates (potentially bad), and heavy hydration is a leading cause of poor Interaction to Next Paint. Understanding hydration is understanding the gap between "looks loaded" and "actually responds".

• JavaScript makes server-rendered HTML interactive in the browser
• The page can look loaded but not respond until hydration completes
• Heavy hydration is a leading cause of poor INP

The cost and how frameworks reduce it

Classic full-page hydration re-processes the entire app on the client to make it interactive, which on a large page means shipping and executing a lot of JavaScript before anything responds — blocking the main thread and hurting INP. Modern approaches attack this: partial or progressive hydration hydrates only interactive components; islands architecture hydrates independent interactive "islands" while the rest stays static HTML; and streaming plus selective hydration prioritises the parts the user is likely to interact with first. The goal is to ship far less JavaScript and make interactivity arrive where and when it is needed, not all at once.

• Full hydration re-processes the whole app, blocking the main thread
• Partial/progressive hydration only hydrates interactive components
• Islands architecture keeps most of the page static, hydrating discrete islands
• Streaming and selective hydration prioritise likely-interacted parts

Worked example

A content site server-renders its article pages, so they paint instantly and score well on LCP — but real users complain the page feels frozen for a moment when they tap the menu or a share button, and its INP is poor. The cause is hydration: a large client bundle must download and hydrate the entire page before any interaction responds. The fix is to stop hydrating what does not need it — the article body is static HTML that never needed JavaScript, so only the interactive components (menu, share widget, comments) are made "islands" that hydrate independently and lazily. The JavaScript shipped drops dramatically, the main thread frees up, and INP moves into the green. The example shows hydration's central trade-off: server rendering makes a page look ready, but only disciplined, minimal hydration makes it actually respond quickly.