Out-of-Order Streaming
You'll learn how React optimizes streaming by sending fast content first, regardless of where it appears in the component tree.
The Core Idea
Imagine a webpage where a slow database query sits at the top of the page, and fast static content sits at the bottom. With traditional streaming, you'd wait for the top content before sending anything below it. Out-of-order streaming breaks this constraint: React can send faster Suspense boundaries first, even if they appear later in the tree, then inject slower boundaries into their correct positions when ready.
Think of it like a restaurant serving dishes as they're finished, not strictly in the order they were listed on the menu. Fast dishes get to the table immediately; slow ones arrive later but are placed in the right spot.
How It Works
When you use renderToPipeableStream with multiple Suspense boundaries:
- React sends the initial shell with placeholders for all suspended boundaries
- As data resolves, React streams HTML for the fastest boundary first
- Inline scripts tell the browser where to inject each chunk
- Slower boundaries arrive later and slot into their designated positions
- Hydration happens progressively as content arrives
The browser sees boundaries complete out of order, but the final page structure matches your component tree exactly.
Why This Matters
This approach dramatically improves perceived performance. Users see something useful immediately—perhaps a sidebar or footer—while the hero section with a slow database query is still loading. The page feels alive and interactive faster, even though total load time might be similar.
Key Takeaway: Out-of-order streaming lets React prioritize sending fast Suspense boundaries first, regardless of their tree position, optimizing for the quickest possible user experience while maintaining correct final structure.