Angular Hydration 3

In Part 1 and Part 2, we explored what incremental hydration is, why it matters for performance, and how it affects core web vitals like LCP, INP, and CLS. Now, we'll look at how to implement incremental hydration in a real-world Angular application. We’ll cover the basic setup, hydration triggers, and important considerations to ensure a seamless integration.

Setting Up SSR in Angular

Before exploring incremental hydration patterns, we’ll need to set up server-side rendering (SSR). If your application is not already SSR-enabled, refer to Angular’s official SSR documentation for up-to-date instructions. Setting up SSR creates the foundation for incremental hydration, allowing your app to render on the server and transition smoothly to the client.

Enabling Incremental Hydration

Once SSR is configured, the next step is to enable incremental hydration in your app.config.ts (or equivalent) by adding the withIncrementalHydration() function.  This integration brings together SSR and client-side hydration, giving you control over when specific components are hydrated and allowing you to delay hydration where it makes sense:

// app.config.ts

import { ApplicationConfig } from '@angular/core';
import {
  provideClientHydration,
  withIncrementalHydration,
} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
 providers: [
   provideClientHydration(
     // withEventReplay(), -> automatically included
     withIncrementalHydration()
   ),
 ]
};

This minimalistic setup makes it incredibly easy for developers to enable incremental hydration without dealing with complex configurations.

Using the @defer Syntax

The @defer template syntax is key to incremental hydration in Angular. It allows developers to keep apps responsive by deferring the rendering of specific components until they’re actually needed. Starting with Angular 19, hydration triggers make this feature even more powerful, letting you control exactly when and how a component hydrates based on user interactions or other events.

// overview-page.component.ts

@defer(hydrate on interaction) {
  
}

This approach helps you load JavaScript strategically: not too soon, not too late, but precisely when needed. It’s especially useful for postponing the loading of complex third-party libraries, image-heavy sections, or less frequently visited parts of your app.

Hydration Triggers

Hydration triggers determine when a component should hydrate. You can use them individually or combine them with regular @defer triggers for more granular control:

  • interaction: Hydrates when the user first interacts with the component’s area (e.g., a click or tap)

  • timer(): Delays hydration until a specified time or condition has passed

  • idle: Waits until the browser is idle (no immediate tasks), etc.

@defer(hydrate on interaction; preload on idle) {
  
}

If you decide not to hydrate a component at all, you can specify:

@defer(hydrate never) {
  
}

hydration 3

Hydration Implementation Patterns

As you adopt incremental hydration, consider the following implementation patterns to optimize performance and user experience:

  1. Small Components. Items like dynamic lists or media elements that don’t require immediate interactivity can be deferred, which reduces the initial JavaScript load and keeps the main thread free.

  2. Big Components. Heavier features are best hydrated only when the user navigates to them or interacts with a specific toggle.

  3. Network Constraints. On slower networks, large, lazy-loaded chunks can hamper initial rendering. Incremental hydration helps you load minimal HTML first, deferring heavier downloads until necessary.

  4. UI Complexity. More complex UI segments can remain unhydrated until they are actively engaged with, preventing the user from waiting through large initialization overheads.

💡 Tip

Don’t guess – measure! Tools like WebPageTest, Chrome DevTools, and Lighthouse can help identify which components would benefit most from deferral.

Real-World Considerations

When it comes to implementing incremental hydration and deferred loading in a real-world application, it is important to consider a couple of factors:

  1. How much is the buy-in? Does the complexity allow a setup without bigger refactoring?

  2. Content-Lifetime. Depending on the data rendered, we might have to consider more fitting techniques like pre-rendering, SSG, or ISR.

  3. Smaller devices, in general, have smaller viewports and slower hardware. Be sure to use loading indicators while hydration is ongoing.

Conclusion

Implementing incremental hydration in Angular transforms how your application loads and responds to users. By strategically deferring the hydration of non-critical components, you can achieve faster perceived load times, reduced main thread blocking, and more stable layouts.

Following the steps and patterns discussed in this article will help you integrate incremental hydration smoothly into your Angular projects. This approach not only optimizes performance but also improves the overall user experience, making your applications faster, more responsive, and visually stable.