Suspense Boundaries and Streaming Priority

Suspense boundaries are the fundamental unit of streaming granularity. Each Suspense boundary in your component tree creates an independently streamable section — React can resolve and stream each boundary at its own pace, independent of all others.

The shell consists of everything outside of Suspense boundaries — the layout, navigation, footer, and any synchronously available content. The shell streams first and streams fast, giving users the page structure immediately while data-dependent sections load in the background.

When React streams the shell, any Suspense boundary whose data is not yet available renders as its fallback UI — typically a loading skeleton or spinner. This fallback is included in the initial HTML response, so the user sees a loading indicator immediately rather than a blank space.

When a Suspense boundary's data resolves, React streams the resolved HTML along with a small inline script. That script moves the newly streamed content from a hidden template element into the correct position in the DOM, replacing the fallback without a full page reload.

React uses the HTML template element pattern: resolved Suspense content is streamed into a hidden template, then a script calls a React internal function to swap the template content into the correct DOM position. This enables zero-JS-framework DOM manipulation for the replacement.

Nested Suspense boundaries have independent resolution timelines. An inner Suspense boundary can resolve before its outer boundary — React streams the inner content as soon as it's ready, regardless of whether the outer boundary has resolved. This maximizes parallelism in data loading.

Effective Suspense placement puts slow, data-dependent components inside Suspense boundaries and fast, static, or synchronously available content outside. Navigation bars, hero sections with static text, and footers belong outside. Product listings, user dashboards, and comment feeds belong inside.

React streams Suspense boundaries as they resolve — not necessarily in the order they appear in the document. A below-fold section might resolve before an above-fold section if it requires less data. React handles the DOM insertion correctly regardless of streaming order.

React 18's selective hydration responds to user interaction: if the user clicks or hovers over a Suspense boundary that hasn't hydrated yet, React prioritizes hydrating that boundary first. This ensures user interactions feel responsive even when other parts of the page are still hydrating.

More Suspense boundaries mean more streaming flexibility, but too many add overhead from inline replacement scripts. A practical guideline: wrap entire "sections" (above-fold content, sidebar, below-fold feed) rather than individual components. One to three Suspense boundaries per page is a common sweet spot.

In Chrome DevTools Network tab, use "Preserve log" and observe the response streaming: the HTML document grows in chunks. The Performance tab shows FCP and LCP markers — compare between streaming and non-streaming builds to quantify the improvement. Throttle to Fast 3G to exaggerate the effect.

What happens to a Suspense boundary's fallback in the initial streaming HTML response?

Suspense boundaries divide your React tree into independently streamable sections. The shell (outside Suspense) streams first; fallbacks appear immediately for pending boundaries; resolved content replaces fallbacks via inline scripts. Nested boundaries have independent timelines. Place boundaries at the section level for optimal streaming granularity, and let React's priority system handle interaction-driven hydration order.