Partial Hydration

Server-rendered markup arrives and paints quickly. Full [[hydration]] then walks the entire component tree in the browser, attaching event handlers and rebuilding state, on the main thread, before anything responds to input.

Partial hydration observes that most of a page — header, footer, article body, product description — is static and needs none of that. Only genuinely interactive components are hydrated, and the rest remain markup.

The experience shape it fixes

The failure it addresses is specific and severe: the page looks ready and is not. Users tap, nothing happens, and they tap again — which is worse than a page that is visibly still loading, because the visual signal is actively misleading.

The measurable symptom is a long gap between first contentful paint and interaction readiness, with a long main-thread task sitting between them.

Implementation patterns

• Identify the genuinely interactive components. On most content pages this is a small minority, and the identification alone is usually a large reduction for little effort.
• Defer hydration until visible or until interaction, so the initial cost covers only what is above the fold.
• Send less JavaScript, since hydration cost is proportional to code executed — route-level splitting attacks the cause rather than the symptom.
• Prefer approaches that never hydrate the page as a whole: islands, server components, or plain progressive enhancement where the interactivity is simple.
• Keep server and client markup identical, because a mismatch forces a full client re-render and discards the benefit entirely — this is the most common way a partial hydration implementation silently stops working.

Industry example

Commerce and content sites consistently find that this problem is invisible in development and severe in the field. The developer's machine executes the hydration work in a fraction of the time a mid-range phone takes, so the gap that users experience as several unresponsive seconds does not appear locally at all.

The teams that make progress change what they measure first: interaction readiness on a representative low-end device, rather than paint timing on a laptop. Optimising the metric that was already good is the most common reason this problem survives months of effort.

Failure scenarios

• Hydrating everything by default, which is what most frameworks do unless configured otherwise.
• Measuring paint rather than interactivity, so the problem is invisible in the dashboard.
• Testing on fast devices, where the effect does not manifest.
• Markup mismatch between server and client, silently triggering full re-render.
• Islands that grow, where a component initially static acquires interactivity and nobody revisits the hydration boundary.

Trade-offs

Partial hydration adds architectural complexity: the boundary between hydrated and static must be decided, maintained, and understood by everyone working in the codebase. State shared across the boundary is awkward, and some frameworks make it far easier than others.

For a genuinely application-like product where nearly everything is interactive, the technique offers little and the complexity is not worth it. It pays off most on content-heavy pages with a few interactive elements — which is the majority of pages on the majority of sites.

Interview question

"Your pages paint in under a second and users say they feel broken for several seconds afterwards. What is happening, how would you confirm it, and what is the highest-leverage fix?"