ionic-team · ShaneK · Jun 9, 2026 · Jun 4, 2026 · Jun 9, 2026
@@ -85,22 +85,19 @@ While `core.css` is required, `normalize.css`, `structure.css`, and `typography.
 Update `src/app/app.config.ts` to include `provideIonicAngular`:
 
 ```typescript title="src/app/app.config.ts"
-import { ApplicationConfig, provideBrowserGlobalErrorListeners, provideZoneChangeDetection } from '@angular/core';
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
 import { provideRouter } from '@angular/router';
 
 import { routes } from './app.routes';
 import { provideIonicAngular } from '@ionic/angular/standalone';
 
 export const appConfig: ApplicationConfig = {
-  providers: [
-    provideBrowserGlobalErrorListeners(),
-    provideZoneChangeDetection({ eventCoalescing: true }),
-    provideRouter(routes),
-    provideIonicAngular({}),
-  ],
+  providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes), provideIonicAngular({})],
 };
 ```
 
+This reflects the Angular 21 scaffold, which is zoneless by default. If your existing app is on Angular 18 through 20, it still has `provideZoneChangeDetection({ eventCoalescing: true })`; keep that provider and add `provideIonicAngular({})` alongside it. Refer to [Zoneless Change Detection](/docs/angular/zoneless.md) for details.
+
 ## Using Individual Components
 
 After completing the setup above, you can start using Ionic components in your existing Angular app. Here's an example of how to use them:

@@ -0,0 +1,150 @@
+---
+title: Zoneless Change Detection
+sidebar_label: Zoneless
+---
+
+<head>
+  <title>Zoneless Change Detection with Ionic and Angular</title>
+  <meta
+    name="description"
+    content="Run Ionic Angular apps without Zone.js. Learn the change detection contract for overlays, lifecycle hooks, and platform events when using Angular's zoneless change detection."
+  />
+</head>
+
+Angular 21 makes [zoneless change detection](https://angular.dev/guide/zoneless) the default, removing the dependency on Zone.js. This guide covers what you need to know to run an Ionic Angular app without Zone.js.
+
+With Zone.js, Angular automatically re-renders after almost any asynchronous task. Without it, Angular only re-renders when you explicitly tell it the view is out of date. Most of your app keeps working unchanged, but a few patterns that relied on Zone.js need a small adjustment.
+
+## What keeps working automatically
+
+You do not need to change these. Angular schedules change detection for them in a zoneless app:
+
+- Template event bindings: `(click)`, `(ionChange)`, `(ionInput)`, and every other `(event)` handler.
+- Host listeners (`@HostListener`), including the ones Ionic's form value accessors use, so `[(ngModel)]` and reactive forms stay in sync.
+- Signal updates that are read in a template.
+- The `async` pipe.
+- Ionic page lifecycle hooks (`ionViewWillEnter`, `ionViewDidEnter`, `ionViewWillLeave`, `ionViewDidLeave`) that set state synchronously. Ionic notifies Angular after each hook runs.
+- Navigation, route transitions, and tab switching.
+
+## What needs a notification
+
+When you update component state from an asynchronous callback that Angular did not wrap, nothing schedules a re-render. The state changes, but the view does not update. This applies to any Angular code, not only Ionic, and the common sources in an Ionic app are:
+
+- Awaiting an overlay result, such as `await modal.onWillDismiss()` or `loading.onDidDismiss().then(...)`.
+- Asynchronous work started inside a lifecycle hook, for example a `setTimeout` or `fetch` in `ionViewWillEnter`.
+- `Platform` event subscriptions (`backButton`, `resize`, `pause`, `resume`, keyboard events) and `Platform.ready()`.
+- Any `setTimeout`, `setInterval`, or RxJS subscription that assigns to a component field.
+
+You can notify Angular in two ways: write to a [signal](https://angular.dev/guide/signals) that the template reads, or inject `ChangeDetectorRef` and call `markForCheck()` after the update. We recommend signals because they work the same with or without Zone.js.
+
+### Signals (recommended)
+
+Writing a signal that a template reads schedules change detection automatically, so there is nothing extra to remember after the update.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { ModalController } from '@ionic/angular/standalone';
+import { PickerModal } from './picker.modal';
+
+@Component({
+  selector: 'app-home',
+  template: `
+    <ion-button (click)="pick()">Pick a value</ion-button>
+    <p>Selected: {{ selected() }}</p>
+  `,
+})
+export class HomePage {
+  private modalCtrl = inject(ModalController);
+  readonly selected = signal<string | undefined>(undefined);
+
+  async pick() {
+    const modal = await this.modalCtrl.create({ component: PickerModal });
+    await modal.present();
+
+    const { data } = await modal.onWillDismiss<string>();
+    // Writing the signal updates the view automatically.
+    this.selected.set(data);
+  }
+}
+```
+
+### `ChangeDetectorRef.markForCheck()`
+
+If you are not using signals for a particular piece of state, inject `ChangeDetectorRef` and call `markForCheck()` after the asynchronous update. It is a no-op-or-better under Zone.js, so it is safe to leave in place if you later re-enable zones.
+
+```ts
+import { ChangeDetectorRef, Component, inject } from '@angular/core';
+
+@Component({
+  selector: 'app-list',
+  template: `@for (item of items; track item) { <ion-item>{{ item }}</ion-item> }`,
+})
+export class ListPage {
+  private cdr = inject(ChangeDetectorRef);
+  items: string[] = [];
+
+  ionViewWillEnter() {
+    // Asynchronous work inside a lifecycle hook still needs a notification.
+    setTimeout(() => {
+      this.items = ['A', 'B', 'C'];
+      this.cdr.markForCheck();
+    }, 1000);
+  }
+}
+```
+
+## Common Ionic patterns
+
+These apply the two approaches above to patterns you are likely to hit in an Ionic app.
+
+### Inline overlays with dynamic content
+
+Content projected into an inline `ion-modal` or `ion-popover` follows the same rule. If you populate it asynchronously, update a signal or call `markForCheck()`:
+
+```ts
+@Component({
+  selector: 'app-inline',
+  template: `
+    <ion-popover #popover>
+      <ng-template>
+        <ion-list>
+          @for (item of items(); track item) {
+          <ion-item>{{ item }}</ion-item>
+          }
+        </ion-list>
+      </ng-template>
+    </ion-popover>
+  `,
+})
+export class InlinePage {
+  readonly items = signal<string[]>([]);
+
+  open(popover: IonPopover) {
+    popover.present();
+    setTimeout(() => this.items.set(['A', 'B', 'C', 'D']), 1000);
+  }
+}
+```
+
+Inline overlays also expose their events as outputs (for example `ionModalDidDismiss`), which you can convert to a signal with [`toSignal`](https://angular.dev/api/core/rxjs-interop/toSignal) if you prefer a reactive style.
+
+### Platform events
+
+`Platform` exposes its events as RxJS subjects. Update a signal inside the subscription so the view reflects the change:
+
+```ts
+export class AppComponent {
+  private platform = inject(Platform);
+  readonly isLandscape = signal(false);
+
+  constructor() {
+    this.platform.resize.subscribe(() => {
+      this.isLandscape.set(this.platform.isLandscape());
+    });
+  }
+}
+```
+
+## Staying on Zone.js
+
+If you are not ready to adopt zoneless change detection, you can opt back into Zone.js with `provideZoneChangeDetection()`. Refer to the [Keeping Zone.js section of the Ionic 9 upgrade guide](/docs/updating/9-0.md#keeping-zonejs) for the exact configuration.
@@ -30,14 +30,20 @@ If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to upda
 npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-toolkit@latest
 ```
 
-#### Angular 21 Zoneless Default
+#### Zoneless Change Detection
 
-Angular 21 makes zoneless change detection the default. Ionic 9 relies on zone-based change detection, so you must opt back in with `provideZoneChangeDetection()`. Without it you will see `NG0909` errors and asynchronous updates (such as modal and popover lifecycle, and tab navigation) will not work.
+Ionic 9 supports zoneless change detection. Angular 21 makes zoneless the default, so a new Ionic 9 app on Angular 21 runs without Zone.js out of the box and no change-detection provider is required.
+
+Without Zone.js, Angular does not automatically re-render when you update component state from an asynchronous callback (awaiting an overlay result, `setTimeout`, RxJS subscriptions, `Platform` events). In those cases you must notify Angular with a signal or `ChangeDetectorRef.markForCheck()`. Refer to [Zoneless Change Detection](/docs/angular/zoneless.md) for the patterns Ionic apps use.
 
 :::note
-This step only applies when you are on Angular 21. Angular 18 through 20 are unaffected and require no change.
+On Angular 18 through 20, Zone.js remains Angular's default, so those versions are unaffected and require no action. To adopt zoneless on Angular 18 through 20, add `provideZonelessChangeDetection()` (named `provideExperimentalZonelessChangeDetection()` on Angular 18 and 19) and remove `zone.js` from the `polyfills` array in `angular.json`.
 :::
 
+##### Keeping Zone.js
+
+If you prefer to keep using Zone.js on Angular 21, opt back in with `provideZoneChangeDetection()`.
+
 For standalone applications, add the provider to `bootstrapApplication`:
 
 ```diff
@@ -66,6 +72,12 @@ platformBrowserDynamic()
   .catch((err) => console.error(err));
 ```
 
+Either way, also confirm `zone.js` is listed in the `polyfills` array in `angular.json`. Angular 21's default scaffold omits it:
+
+```json title="angular.json"
+"polyfills": ["zone.js"]
+```
+
 #### TypeScript
 
 Ionic 9 supports TypeScript 5.4 or later, matching the minimum for Angular 18. If you upgrade to Angular 21, it requires TypeScript 5.9 or later.

@@ -94,6 +94,7 @@ module.exports = {
         'angular/testing',
         'angular/storage',
         'angular/performance',
+        'angular/zoneless',
         'angular/pwa',
       ],
     },