Skip to content

PATTERN Cited by 1 source

Suspense Boundary (progressive rendering)

A Suspense boundary is a declarative "this subtree may not be ready yet" marker placed in a component tree. The renderer commits everything outside the boundary immediately, replaces the inside with a fallback (loading placeholder), and resumes rendering the subtree — and emitting its markup — when its dependencies resolve. In React 18, <Suspense fallback={...}> is the concrete API; combined with renderToPipeableStream it becomes the unit of streaming SSR.

Server-side emission shape (React 18)

Pending boundary in initial HTML:

<!--$?-->
  <template id="B:1"></template>
<!--/$-->

When the boundary's data resolves, React streams its completed markup as a later chunk plus inline JS that replaces the <template> by ID and transitions the marker comment to <!--$-->. The browser paints the update in place.

Design properties

  • Failure granularity: a slow dependency on one boundary doesn't block paint of everything else. Placement of boundaries is a deliberate design choice — navigation + chrome above, content body below; fast content above, slow charts below.
  • Hydration granularity: each boundary hydrates independently as its chunk arrives, so interactivity is incremental.
  • Fallback is a design surface: placeholders should not cause layout shift (CLS), and should approximate the final bounding box.

Coupling with data loaders

Boundaries are only useful if data fetching is split to match. Confluence added a granular preloading implementation that mirrors the component tree, letting each preload feed exactly one boundary (Source: sources/2026-04-16-atlassian-streaming-ssr-confluence). Without this, the whole page waits on the slowest loader and streaming degenerates to classic SSR.

Anti-patterns

  • Too many boundaries: each adds hydration/runtime overhead, and in React 18 each additional ready boundary costs one extra render pass across any shared subtree touched by a context change. See concepts/react-hydration.
  • Boundaries around fast, co-located content: pure overhead.
  • Boundaries that forget state injection: the state that drove server rendering must arrive before the boundary's markup or hydration mismatches.

Seen in

Last updated · 200 distilled / 1,178 read