A server streams a product page's HTML, but a recommendations widget in the middle of the page takes 900 ms to load while everything below it is ready immediately. How do teams stop that one slow region from holding up the rest of the streamed document?

## Why document order is a constraint A streamed HTML response is one ordered byte sequence. The parser consumes it front to back, so markup written at position N cannot appear before markup at position N−1. If the server renders regions in document order and awaits each one's data, a single slow region stalls every region below it — the footer, the reviews, and any scripts referenced further down all wait behind the recommendations query. That is a scheduling problem, not a bandwidth problem, and the answer is to decouple *where content appears* from *when it is sent*. ## The placeholder-and-swap pattern The technique is old and well proven — Facebook publicised it as BigPipe, and modern streaming frameworks implement the same idea underneath their own APIs. It has three parts: **1. Emit a placeholder at the right position.** When the parser reaches the widget's slot, the server has no data, so it writes a container instead: ```html <section id="recs" class="recs-skeleton" aria-busy="true"><!-- filled later --></section> ``` The container carries a stable identifier and, ideally, a skeleton that occupies the widget's eventual dimensions. **2. Keep streaming everything else.** The server continues writing the rest of the document immediately. The user gets the complete page structure — header, product details, reviews, footer — while the slow query is still running. **3. Send the late chunk and swap it in.** When the data resolves, the server appends the real markup to the still-open response, wrapped in a `<template>` element so the browser parses it but does not render or load anything inside it. Right after it comes a short inline script that moves the content into the placeholder: ```html <template id="recs-data"><ul><li>Blue mug</li></ul></template> <script> var slot = document.getElementById('recs'); slot.replaceChildren(document.getElementById('recs-data').content); slot.removeAttribute('aria-busy'); </script> ``` The inline script runs the instant the parser reaches it — no round trip, no framework required, no waiting for `DOMContentLoaded`. ## Deciding what deserves a placeholder Not every slow region should be deferred this way. The useful test is whether the region is *the reason the user came*. Defer things that are secondary and slow: recommendations, related content, review lists, personalised badges, availability lookups. Do not defer the primary content of the page — a product's own title, price and hero image — because turning the main content into a late swap delays the largest contentful paint and makes the page look empty at the moment the user is judging it. A second consideration is how many placeholders a page has. Each one is a visible transition; a page that resolves eight regions at eight different moments feels twitchy even though every individual chunk arrived promptly. Grouping related slow regions into one placeholder often feels calmer than resolving each independently. ## The failure mode: layout shift The swap replaces a small placeholder with taller real content, and everything below jumps. This is the most common way an out-of-order streaming implementation makes the experience measurably worse while making the timings look better. The placeholder must reserve height — fixed dimensions, an aspect ratio, or a skeleton built from the same layout as the real widget. Where the final size genuinely varies, cap the container and let the content scroll or clamp inside it rather than letting the page reflow. ## Accessibility and correctness details The placeholder should communicate that it is loading, not pretend to be content: `aria-busy="true"` on the container, removed when the swap completes, is a low-cost signal. If the region can fail, the server needs a path that writes an error state into the placeholder rather than leaving a skeleton spinning forever — once headers are committed, a failed region cannot turn the page into an error response. And a client that has JavaScript disabled will never run the swap script, so the placeholder's own contents are what those users see; for content that must exist without scripting, deferral is the wrong tool. ## What good looks like Done well, the network panel shows one long document request whose body arrives in bursts, the first paint shows a complete page skeleton, the deferred region fills in without moving anything around it, and no region below the slow one waited on it. That is the whole goal: preserve the reading order of the page while abandoning the delivery order.