Server-side rendering gives you a fast first paint, and hydration decides whether you keep it. If the browser can reuse the server's DOM, the page stays put while JavaScript wakes it up. If it can't, Angular has to throw parts of the page away and build them again, which costs CPU time, can make content flicker or jump, and in development fills the console with errors. Almost every hydration problem comes from the same root cause: the browser's first render doesn't produce the same DOM the server sent.

This is lesson 9.3 of the Angular Tutorial. Lesson 9.2 followed a request through the server; this lesson picks up when the HTML reaches the browser. You'll learn how non-destructive hydration works, how to confirm it is running, the coding patterns that break it, and when ngSkipHydration is a reasonable escape hatch. Detailed mismatch debugging, reading NG0500-family errors node by node, gets its own lesson later (lesson 10.8 in the debugging module); here the goal is to avoid the mismatches in the first place.

Destructive vs non-destructive hydration #

Non-destructive hydration is what Angular uses today. During server rendering, Angular adds small annotations to the HTML describing the structure it produced: where each component, @if block and @for row starts and how many nodes it contains. In the browser, Angular creates components as usual, but instead of creating DOM nodes it claims the existing ones, guided by those annotations. The work saved is the DOM creation; the component code, bindings and listeners still run.

Enabling and verifying it #

The CLI adds hydration when you set up SSR. If you're wiring it by hand, add the provider to the browser config; mergeApplicationConfig in app.config.server.ts carries it to the server, which is required, because the server is what writes the annotations.

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideHttpClient, withFetch } from '@angular/common/http';
import { provideClientHydration } from '@angular/platform-browser';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideHttpClient(withFetch()),
    provideClientHydration(),
  ],
};

In Angular v22, provideClientHydration() with no arguments also turns on incremental hydration and event replay, which lessons 9.4 and 9.5 cover.

To confirm it works, open the browser console on a server-rendered page in development mode. Angular logs a hydration summary with the number of components and nodes it hydrated. Angular DevTools can also overlay the page to show which components were hydrated and which were skipped. If you see no summary, check that the provider is present on both sides and that you are actually loading a server-rendered page, not a client-rendered route.

The rule: same DOM on both sides #

Hydration needs the browser's first render to produce exactly the DOM structure the server produced. Anything that makes them differ is a potential failure:

Direct DOM manipulation #

This is the most common cause in real code, usually inherited from pre-SSR components or third-party libraries.

// Breaks hydration: creates DOM nodes Angular doesn't own, during rendering
@Component({ selector: 'app-badge', template: `<span #host></span>` })
export class Badge {
  private host = viewChild.required<ElementRef<HTMLElement>>('host');
  count = input(0);

  constructor() {
    effect(() => {
      this.host().nativeElement.innerHTML = `<b>${this.count()}</b>`;
    });
  }
}

// Hydration-friendly: let the template own the DOM
@Component({
  selector: 'app-badge',
  template: `<span><b>{{ count() }}</b></span>`,
})
export class Badge {
  count = input(0);
}

When you genuinely need imperative DOM work, such as a chart library that draws into a container, do it in afterNextRender. That callback runs only in the browser and only after hydration has claimed the DOM, so it doesn't interfere:

constructor() {
  afterNextRender(() => {
    renderChart(this.container().nativeElement, this.data());
  });
}

The template should render an empty, stable container on both platforms; the library fills it in afterwards.

Invalid HTML nesting #

Browsers parse HTML leniently. When the server sends <p><div>Price</div></p>, the parser closes the <p> before the <div>, producing a different tree from the one Angular serialized. The server's string looked fine; the browser's DOM doesn't match it.

<!-- Repaired by the parser, breaks hydration -->
<p class="summary">
  <div class="price">{{ price() | currency }}</div>
</p>

<table>
  @for (row of rows(); track row.id) {
    <tr><td>{{ row.name }}</td></tr>
  }
</table>

<!-- Valid: hydrates cleanly -->
<div class="summary">
  <div class="price">{{ price() | currency }}</div>
</div>

<table>
  <tbody>
    @for (row of rows(); track row.id) {
      <tr><td>{{ row.name }}</td></tr>
    }
  </tbody>
</table>

Running your rendered HTML through a validator catches these quickly. Watch for components whose host element ends up in an invalid position, such as a component with a <div> template used inside a <p>.

Platform-dependent templates #

It's tempting to hide browser-only widgets with a platform check:

// Avoid: server renders nothing, browser renders the map
isBrowser = isPlatformBrowser(inject(PLATFORM_ID));

@if (isBrowser) {
  <app-store-map />
}

The server and browser now disagree about the DOM, and the page shifts when the map appears. Better options, in order:

For values like the current time, compute them once on the server and transfer them (lesson 9.6), or format them in the browser after hydration. Rendering new Date() directly produces different text on each side.

ngSkipHydration: the escape hatch #

Adding ngSkipHydration to a component's host element tells Angular not to hydrate that component or its children. Angular removes its server-rendered DOM and renders it again from scratch on the client, as if hydration were disabled for that subtree.

<app-legacy-carousel ngSkipHydration />

Or permanently, from the component itself:

@Component({
  selector: 'app-legacy-carousel',
  host: { ngSkipHydration: 'true' },
  templateUrl: './legacy-carousel.html',
})
export class LegacyCarousel {}

The rules:

• Component host elements only. On a plain element it has no effect and raises error NG0504.
• Not on the root component. That effectively disables hydration for the whole app.
• It's a workaround, not a fix. The skipped subtree loses the benefits of hydration and may flicker when it is re-rendered. Track each use and remove it once the underlying component is fixed.

The hydration errors you'll meet #

Angular reports hydration problems with numbered errors. You don't need to memorise them, but recognising the family helps you jump to the right cause:

Lesson 10.8 walks through debugging these node by node, including reading the expected-versus-actual DOM that Angular prints.

Gotchas #

What's next #

Lesson 9.4 deals with the gap between "visible" and "interactive": what happens to clicks and key presses that arrive before hydration finishes, how event replay captures and replays them, and which events it doesn't cover.

Try it yourself #

Load three server-rendered pages of your app in development mode and note the hydration summary for each. Search your templates for isPlatformBrowser, innerHTML and <p> elements that contain components, and fix one mismatch source. Then list every ngSkipHydration in the codebase with the reason it exists.