Skip to content

Angular @defer and SSR: the placeholder is what crawlers get

With Angular @defer and SSR, the server renders only the @placeholder unless incremental hydration and a hydrate trigger are set. How to check and fix it.

By Crawlito · 8 min read

In short

  • Angular's defer guide says that on the server, in both SSR and SSG, a @defer block renders its @placeholder, or nothing if there is none, and its triggers are not invoked.
  • To put a @defer block's main content in the server HTML, Angular says to enable incremental hydration and give that block a hydrate trigger such as hydrate on viewport.
  • Since Angular 22, incremental hydration is on by default with provideClientHydration(); in Angular 19 to 21 you add withIncrementalHydration() yourself.
  • A crawler that reads only the raw HTML never fires an on viewport or on interaction trigger, so content inside a plain @defer block is missing from what it receives.
  • Google says Search does not interact with pages, so content that loads only after scrolling, clicking or another user action is a risk even for Googlebot's renderer.
On this page

On a server-rendered Angular page, a plain @defer block does not put its content in the HTML. Angular's defer guide says that on the server, for both SSR and static generation, defer blocks render their @placeholder, or nothing if there is no placeholder, and the triggers are never invoked. To ship the real content in the HTML, you enable incremental hydration and add a hydrate trigger to the block. Without that, a crawler that reads only the server response gets your placeholder text, a skeleton or an empty space.

This post assumes SSR or prerendering already works. If it does not, start with Angular SSR for crawlers and AI, which covers @angular/ssr, render modes, metadata and 404s. Here the question is narrower: which parts of an already server-rendered page are missing because of @defer, and how to bring them back.

What a @defer block renders on the server

A @defer block splits the code for the components, directives and pipes inside it into a separate JavaScript chunk that loads later. You choose when with triggers (on idle, the default, plus on viewport, on interaction, on hover, on immediate, on timer and when) and you describe the waiting state with @placeholder, @loading and @error sub-blocks.

Here is a typical product page section:

html
@defer (on viewport) {
  <app-product-specs [product]="product" />
} @placeholder {
  <div class="specs-skeleton">Loading specifications</div>
}

In the browser, the placeholder shows until it scrolls into view, then Angular loads the chunk and swaps in <app-product-specs>. On the server, Angular renders only the placeholder. The server HTML for that section contains the skeleton div and the words "Loading specifications". The specs table is not there.

Server render of the blockWhat ends up in the HTML
@defer with a @placeholder, no hydrate triggerThe placeholder content only
@defer with no @placeholder, no hydrate triggerNothing for that block
@defer with a hydrate trigger and incremental hydration enabledThe main content of the block
Route set to RenderMode.ClientNo server render at all, so none of the above

Angular's guide also notes that by default, defer blocks render no content before they are triggered, so a block without a placeholder leaves no trace in the server HTML.

Why crawlers end up with the placeholder

The triggers are browser events. on viewport uses IntersectionObserver, on interaction waits for a click or keydown, on hover waits for mouseover or focusin, and on idle waits for requestIdleCallback. None of them runs on the server, and none of them runs for a crawler that downloads the HTML and does not execute JavaScript. For that kind of crawler, the server HTML is the whole page. Measurements of which AI crawlers run scripts are collected in do AI crawlers run JavaScript.

Crawlers that do render JavaScript are not safe either. Google's lazy-loading guidance says Google Search does not interact with your page, and asks that content load when it is visible in the viewport, not on scrolling or clicking. A block behind on interaction or on hover waits for an action that never comes. Google lists IntersectionObserver, which on viewport uses, among its recommended lazy-loading methods, but it does not document how its renderer handles Angular's on idle or on viewport triggers, so treat those as unverified too. The same pattern with tabs and accordions is covered in lazy-loaded tabs, accordions and hidden content.

How to find which blocks ship placeholders

Start from the code, then confirm against the deployed HTML.

1. List the @defer blocks without a hydrate trigger

bash
grep -rn "@defer" src --include="*.html" --include="*.ts" | grep -v "hydrate"

Each line it prints is a likely candidate for a block that renders only its placeholder on the server. It is a rough filter: a hydrate trigger written on the next line, or a match inside a comment, needs a manual look. Placeholder-only is fine for a chat widget or a map. It is a problem for product details, prices, reviews, FAQs, article body text or internal links.

2. Compare the raw HTML with what you see

Pick a sentence that appears inside a deferred component, then fetch the page without running scripts:

bash
curl -s https://example.com/products/blue-kettle | grep -c "Capacity: 1.7 litres"
curl -s https://example.com/products/blue-kettle | grep -c "Loading specifications"

If the first count is 0 and the second is 1, the server sent the placeholder. Check with a crawler user agent too, in case your hosting treats bots differently; see your page as an AI crawler with curl has the commands. The general method is in raw vs rendered HTML.

3. Check the hydration setup

Look at the providers passed to bootstrapApplication (often in app.config.ts). Angular's incremental hydration guide says the feature is for apps that already use SSR with hydration, so provideClientHydration() has to be there. On Angular 22 and later, look for withNoIncrementalHydration(), which turns the feature off. On Angular 19 to 21, look for withIncrementalHydration(), which turns it on.

How to render @defer content on the server with incremental hydration

Incremental hydration lets Angular render a block's main template on the server and leave it dehydrated in the browser until a trigger fires. Angular's incremental hydration guide says that adding a hydrate trigger tells Angular to load the block's dependencies during server-side rendering and render the main template rather than the @placeholder. On the client, the code stays deferred until the hydrate trigger fires. So you keep the smaller initial bundle and the content is in the HTML.

It requires SSR with hydration. How you switch it on depends on your Angular version:

Angular versionHow incremental hydration is enabled
22 and later (the current angular.dev guide at the time of writing)On by default with provideClientHydration(); opt out with withNoIncrementalHydration()
19 to 21Add withIncrementalHydration() to provideClientHydration()

Angular's changelog shows the API added in 19.0.0, marked stable in 20.0.0 and made the default in 22.0.0. On 19 to 21, the call looks like this:

ts
import {
  bootstrapApplication,
  provideClientHydration,
  withIncrementalHydration,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withIncrementalHydration())],
});

Angular says incremental hydration depends on event replay and turns it on automatically, so a separate withEventReplay() can be removed.

Then add a hydrate trigger to each block whose content should be in the HTML. The regular trigger stays and still applies to client-side navigation:

html
@defer (on viewport; hydrate on viewport) {
  <app-product-specs [product]="product" />
} @placeholder {
  <div class="specs-skeleton">Loading specifications</div>
}

The hydrate triggers mirror the regular ones: hydrate on idle, hydrate on viewport, hydrate on interaction, hydrate on hover, hydrate on immediate, hydrate on timer, hydrate when and hydrate never. For a crawler, all of them have the same effect: the main content is in the server HTML. The choice only changes when the browser downloads the code and makes the section interactive. hydrate never is useful for content that is purely static, such as a long description: Angular renders it on the server and never hydrates it on the initial load.

Two details from Angular's guide matter here:

  • Keep the @placeholder. It is not used for incremental hydration, but Angular still renders it when a user reaches the route through client-side navigation, because the block then behaves like a regular @defer block. A crawler that fetches each URL as a fresh request gets the server-rendered version instead.
  • The same constraints as full hydration apply. Angular lists limits on direct DOM manipulation and a requirement for valid HTML structure. If a deferred component breaks hydration, fix it rather than reaching for ngSkipHydration, which makes the component destroy and re-render itself in the browser.

After the change, rebuild, deploy and run the curl | grep check again. The specs sentence should now return 1.

Which content should stay out of @defer

Incremental hydration fixes the server HTML, but some content is simpler to keep outside @defer altogether:

  • Above-the-fold content. Angular's defer guide warns that deferring components visible on initial load can increase Cumulative Layout Shift. The incremental hydration guide says hydrate triggers remove that shift, but plain @defer does not.
  • Anything a crawler needs to understand the page: the <h1>, the main copy, prices, availability, and the links to related pages. A small component here saves little bundle size and costs a lot if it goes missing.
  • Structured data. If a deferred component outputs JSON-LD, the markup is not in the server HTML without a hydrate trigger.

And some content is a good fit for plain @defer, because nobody needs it in the HTML: chat widgets, video players, maps, comment editors, charts that repeat a table already on the page, and anything behind a login.

ContentPlain @defer@defer with a hydrate triggerNo @defer
Heading, intro, pricesAvoidWorksBest
Specs, FAQs, reviews below the foldAvoidGood fitWorks
Internal links and related itemsAvoidGood fitWorks
Chat, maps, video, editorsGood fitNot neededHeavier bundle

How to keep it from regressing

A new @defer block is easy to add and easy to miss in review. Add the source check from earlier to your pull request checklist, and keep a short list of sentences that must appear in the raw HTML of each template. Run the curl | grep checks after every deploy, against the real URL, since hosting and caching are part of what crawlers receive. Angular's guide also notes that while Hot Module Replacement is active, all @defer chunks are fetched eagerly and the configured triggers are overridden, and that serving with --no-hmr restores normal trigger behaviour. A dev server with HMR is not a reliable test of what a deferred block does; the deployed server response is.

Frequently asked questions

Does Angular @defer hurt SEO?

Only for content a crawler needs. On the server, a @defer block without a hydrate trigger renders just its placeholder, so that content is missing from the HTML. With incremental hydration and a hydrate trigger, the main content is server-rendered.

Does @defer (on idle) render on the server?

No. Angular's guide says triggers are not invoked on the server, including the default idle trigger. Add a hydrate trigger, such as hydrate on idle, to render the main content during SSR.

Do I still need a @placeholder with incremental hydration?

Yes. Angular says the placeholder is not used for incremental hydration but is still needed when the block is rendered through client-side navigation.

Does incremental hydration work with prerendering?

Yes. Angular's defer guide says that with incremental hydration and hydrate triggers, the main content of @defer blocks renders on the server for both SSR and SSG. Routes set to RenderMode.Client are not server-rendered at all.

No promise. It puts the content into the HTML that crawlers receive. Whether an assistant uses or cites a page depends on many factors outside your site.

Check what your deferred sections send

The free check fetches one page the way AI crawlers do, with no account, and shows whether your main text is in the raw HTML. Run it on a template with @defer blocks before and after adding hydrate triggers to confirm the content is now there.

Filed under Rendering and content. Topics: angular, ssr, rendering, raw-html