Progressive Hydration with Selective Hydration

Selective hydration is a React 18 feature that allows React to begin hydrating components as soon as their JavaScript code arrives, without waiting for the entire page's JavaScript to download. Each independently code-split section hydrates as its bundle loads, not all at once.

Before React 18, hydration was "all or nothing" — React had to download all JavaScript and hydrate the entire tree before any part of the page became interactive. React 18 breaks this constraint: portions of the tree hydrate independently as their code and data become available.

If the user clicks on or interacts with a Suspense boundary that hasn't been hydrated yet, React immediately prioritizes hydrating that subtree before any other pending hydration work. This means the thing the user is trying to use becomes interactive first, even if it's not in document order.

Combining React.lazy with dynamic imports and Suspense boundaries enables selective hydration for code-split components. The browser downloads the main JS bundle first, hydrating the shell immediately. Each lazy-loaded component hydrates when its chunk downloads — progressively, as the browser fetches them.

The result is that above-the-fold content becomes interactive before below-fold JavaScript has even been downloaded. A user can interact with the navigation and hero CTA while the comment feed and recommendation widget are still loading their JavaScript chunks.

Selective hydration reduces Total Blocking Time (TBT) — the key metric for hydration performance. In Chrome DevTools Performance tab, Long Tasks (tasks over 50ms) are highlighted in red. Before selective hydration, you might see one 300ms Long Task for full hydration; after, you see several small tasks staggered over time.

The anti-pattern that undermines selective hydration is importing all components at the top of your app: import Footer from './Footer'. This forces the browser to download, parse, and execute Footer's code before any hydration begins. Replace top-level imports of below-fold components with React.lazy + dynamic imports.

Use const Footer = React.lazy(() => import('./Footer')) for components that appear below the initial viewport. Wrap them in Suspense with a simple fallback. The browser de-prioritizes fetching Footer's bundle until above-fold hydration is complete, naturally improving TBT.

Streaming and selective hydration are complementary: streaming sends HTML chunks to improve FCP and LCP, while selective hydration processes JavaScript chunks to improve TTI and TBT. Together they address both the "show content fast" and "make it interactive fast" dimensions of performance.

React Server Components take selective hydration further: server components produce no JavaScript at all for the client. Only client components (marked with "use client") need to be hydrated. This reduces the total amount of JavaScript that needs to hydrate, making selective hydration even more effective.

A practical pattern: use renderToPipeableStream for streaming HTML, wrap the page in a root hydrateRoot call (instead of createRoot) to enable hydration mode, use React.lazy for all below-fold sections, and wrap each section in a Suspense boundary. React handles the rest automatically.

How does user interaction affect selective hydration priority in React 18?

Selective hydration lets React hydrate component subtrees progressively as their JavaScript arrives, rather than waiting for the full bundle. User interactions prioritize hydration of the targeted subtree. React.lazy + dynamic imports for below-fold content, combined with Suspense boundaries, enables this progressive pattern. Selective hydration and streaming SSR are complementary techniques that together address both content delivery and interactivity performance.