feat(angular): default to zoneless change detection (#31196)

Issue number: resolves #30804

---------

## What is the current behavior?

Currently, on `major-9.0`, `@ionic/angular` still defaulted to Zone.js.
The `ng add` schematic registered `provideZoneChangeDetection()`, and
`zone.js` was a required peer dependency on both `@ionic/angular` and
`@ionic/angular-server`. Angular 21 bootstraps zoneless out of the box,
so Ionic was actively opting new apps back into Zone.js.


## What is the new behavior?

Ionic 9 now defaults to zoneless change detection while keeping Zone.js
as a supported opt-in. The `ng add` schematic no longer registers
`provideZoneChangeDetection()`, and `zone.js` is now an optional peer
dependency on both `@ionic/angular` and `@ionic/angular-server`.


## Does this introduce a breaking change?

- [X] Yes
- [ ] No

Apps that want to keep Zone.js on Angular 21 must opt back in with
`provideZoneChangeDetection()` AND keep `import 'zone.js'` in their
polyfills (Angular 21's default scaffold omits it). Under zoneless,
state updated from async callbacks Angular doesn't wrap needs a signal
or a `markForCheck()` call. Template bindings, `@HostListener`, reactive
forms, and synchronous lifecycle-hook state are unaffected. Angular 18
through 20 keep Angular's Zone.js default and need no change.
BREAKING.md is updated with the full migration path.

## Other information

- Test apps run dual-mode for coverage: ng21 is zoneless, ng18-20 stay
on Zone.js. Shared `base/` test pages use the new `assertZoneContext()`
helper (`base/src/app/zone-assert.util.ts`), which asserts in-zone only
when Zone.js is present, so the same pages pass in both modes.

Current dev build (2026-06-08):
```
8.8.9-dev.11781013468.1ed93da9
```

Test app:
https://ionic-framework-git-feat-zoneless-ionic1.vercel.app/angular/

Docs PR: ionic-team/ionic-docs#4541
Docs Preview URL:
https://ionic-docs-git-feat-zoneless-v2-ionic1.vercel.app/docs/updating/9-0#zoneless-change-detection

Author: ShaneK

.gitignore

@@ -68,6 +68,7 @@ core/www/
 # playwright
 core/test-results/
 core/playwright-report/
+packages/angular/test-results/
 
 # ground truths generated outside of docker should not be committed to the repo
 core/**/*-snapshots/*

BREAKING.md

@@ -128,9 +128,17 @@ Apps that relied on `ionChange` firing on every confirmation (for example, to de
 
 Ionic 9 requires Angular 18 or later. Angular 16 and 17 are no longer supported.
 
-**Angular 21 Requires Explicit Zone Change Detection**
+**Zoneless Change Detection by Default**
 
-Angular 21 defaults `bootstrapModule()` and `bootstrapApplication()` to zoneless change detection. `zone.js` in your polyfills is ignored unless you opt back in explicitly, which surfaces as runtime `NG0909` errors and breaks change detection for asynchronous updates (modal and popover lifecycle, tab navigation, and anything depending on async-resolved state). Ionic 9 relies on zone-based change detection, so apps on Angular 21 must provide it explicitly.
+Ionic 9 defaults to zoneless change detection. Angular 21 bootstraps zoneless out of the box, so a new Ionic 9 app on Angular 21 runs without Zone.js and requires no change-detection provider. The `ng add @ionic/angular` schematic no longer registers `provideZoneChangeDetection()`.
+
+Because Zone.js no longer triggers change detection automatically, component state that you update from an asynchronous callback that Angular doesn't wrap (awaiting an overlay result such as `modal.onWillDismiss()`, `setTimeout`, RxJS subscriptions, `Platform` events) no longer re-renders on its own. Update a signal or call `ChangeDetectorRef.markForCheck()` in those callbacks. Template event bindings, `@HostListener`, reactive forms, and Ionic lifecycle hooks (`ionViewWillEnter`, etc.) that set state synchronously are unaffected. Refer to the [Zoneless Change Detection guide](https://ionicframework.com/docs/angular/zoneless) for the patterns.
+
+On Angular 18 through 20, Zone.js remains Angular's default, so those versions are unaffected and require no change. To adopt zoneless there, add `provideZonelessChangeDetection()` (named `provideExperimentalZonelessChangeDetection()` on Angular 18 and 19).
+
+**Keeping Zone.js on Angular 21 (optional)**
+
+To keep using Zone.js on Angular 21, opt back in with `provideZoneChangeDetection()` and keep `zone.js` in your polyfills.
 
 Standalone bootstrap:
 
@@ -160,7 +168,12 @@ NgModule bootstrap:
     .catch((err) => console.error(err));
 ```
 
-Angular forbids `provideZoneChangeDetection()` inside an NgModule's `providers` array, so for NgModule apps it must be passed as `applicationProviders` on the `bootstrapModule()` call. This step is only required on Angular 21. Angular 18 through 20 are unaffected.
+Angular forbids `provideZoneChangeDetection()` inside an NgModule's `providers` array, so for NgModule apps it must be passed as `applicationProviders` on the `bootstrapModule()` call. Both paths also require `zone.js` in your polyfills, which Angular 21's default scaffold omits:
+
+```ts
+// src/polyfills.ts
+import 'zone.js';
+```
 
 **TypeScript**
 

core/src/components/modal/modal.tsx

@@ -439,6 +439,7 @@ export class Modal implements ComponentInterface, OverlayInterface {
    */
   @Event() ionDragEnd!: EventEmitter<ModalDragEventDetail>;
 
+  @Watch('breakpoints')
   breakpointsChanged(breakpoints: number[] | undefined) {
     if (breakpoints !== undefined) {
       this.sortedBreakpoints = breakpoints.sort((a, b) => a - b);

core/src/components/modal/test/sheet/modal.e2e.ts

@@ -399,4 +399,51 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, config }) =>
       expect(Object.keys(dragEndEvent.detail).length).toBe(5);
     });
   });
+
+  test.describe(title('sheet modal: late breakpoints binding'), () => {
+    test('should not crash when swiped after breakpoints are set after the modal loads', async ({ page }) => {
+      const pageErrors: string[] = [];
+      page.on('pageerror', (err) => pageErrors.push(err.message));
+
+      await page.setContent(
+        `
+        <ion-modal initial-breakpoint="1">
+          <ion-content>Modal Content</ion-content>
+        </ion-modal>
+      `,
+        config
+      );
+
+      const modal = page.locator('ion-modal');
+
+      /**
+       * Simulates a JS framework (e.g. Angular with zoneless change detection)
+       * applying the `breakpoints` binding after the web component has finished
+       * loading. `setContent` resolves after `componentDidLoad`, so this lands
+       * too late for the manual `breakpointsChanged()` call in `componentDidLoad`
+       * to pick it up
+       */
+      await modal.evaluate((el: HTMLIonModalElement) => {
+        el.breakpoints = [0, 1];
+      });
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+      const ionModalDidDismiss = await page.spyOnEvent('ionModalDidDismiss');
+
+      await modal.evaluate((el: HTMLIonModalElement) => el.present());
+      await ionModalDidPresent.next();
+
+      // Swiping the sheet down should snap it to breakpoint 0 and dismiss it
+      // without throwing an error
+      const handle = page.locator('ion-modal .modal-handle');
+      await expect(handle).toBeVisible();
+      await dragElementBy(handle, page, 0, 600);
+
+      // Flush any pending errors from the gesture's end handler
+      await page.evaluate(() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+      expect(pageErrors).toEqual([]);
+
+      await ionModalDidDismiss.next();
+    });
+  });
 });

packages/angular-server/package.json

@@ -41,6 +41,11 @@
     "rxjs": ">=7.5.0",
     "zone.js": ">=0.13.0"
   },
+  "peerDependenciesMeta": {
+    "zone.js": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@angular/animations": "^21.0.0",
     "@angular/common": "^21.0.0",

packages/angular/README.md

@@ -72,7 +72,7 @@ This guide shows you how to test the local Ionic Framework build with a new Angu
     ```sh
     # Change to whichever directory you want the app in
     cd ~/Documents/
-    ng new my-app --style=css --ssr=false --zoneless=false
+    ng new my-app --style=css --ssr=false
     cd my-app
     ```
 

packages/angular/common/src/directives/navigation/stack-controller.ts

@@ -41,7 +41,7 @@ export class StackController {
   createView(ref: ComponentRef<any>, activatedRoute: ActivatedRoute): RouteView {
     const url = getUrl(this.router, activatedRoute);
     const element = ref?.location?.nativeElement as HTMLElement;
-    const unlistenEvents = bindLifecycleEvents(this.zone, ref.instance, element);
+    const unlistenEvents = bindLifecycleEvents(this.zone, ref.changeDetectorRef, ref.instance, element);
     return {
       id: this.nextId++,
       stackId: computeStackId(this.tabsPrefix, url),

packages/angular/common/src/index.ts

@@ -5,7 +5,7 @@ export { NavController } from './providers/nav-controller';
 export { Config, ConfigToken } from './providers/config';
 export { Platform } from './providers/platform';
 
-export { AngularDelegate, bindLifecycleEvents, IonModalToken } from './providers/angular-delegate';
+export { AngularDelegate, IonModalToken } from './providers/angular-delegate';
 
 export type { IonicWindow } from './types/interfaces';
 export type { ViewDidEnter, ViewDidLeave, ViewWillEnter, ViewWillLeave } from './types/ionic-lifecycle-hooks';

packages/angular/common/src/providers/angular-delegate.ts

@@ -1,5 +1,6 @@
 import {
   ApplicationRef,
+  ChangeDetectorRef,
   ComponentRef,
   createComponent,
   EnvironmentInjector,
@@ -228,11 +229,21 @@ export const attachView = (
       hostElement.classList.add(cssClass);
     }
   }
-  const unbindEvents = bindLifecycleEvents(zone, instance, hostElement);
+  const unbindEvents = bindLifecycleEvents(zone, componentRef.changeDetectorRef, instance, hostElement);
   container.appendChild(hostElement);
 
   applicationRef.attachView(componentRef.hostView);
 
+  /**
+   * Run change detection on the freshly attached view so Angular's init hooks
+   * (`ngOnInit`, `ngAfterViewInit`) fire before the web component dispatches its
+   * Ionic lifecycle events (`ionViewWillEnter`, etc.). `createComponent` only runs
+   * the creation pass. The init hooks run during an update pass. Under Zone.js an
+   * implicit tick used to cover this, but zoneless Angular schedules no such tick,
+   * so without this the first `ionViewWillEnter` could run before `ngOnInit`.
+   */
+  componentRef.changeDetectorRef.detectChanges();
+
   elRefMap.set(hostElement, componentRef);
   elEventsMap.set(hostElement, unbindEvents);
   return hostElement;
@@ -246,10 +257,29 @@ const LIFECYCLES = [
   LIFECYCLE_WILL_UNLOAD,
 ];
 
-export const bindLifecycleEvents = (zone: NgZone, instance: any, element: HTMLElement): (() => void) => {
+export const bindLifecycleEvents = (
+  zone: NgZone,
+  changeDetectorRef: ChangeDetectorRef,
+  instance: any,
+  element: HTMLElement
+): (() => void) => {
+  /**
+   * `zone.run` keeps the listener registration (and, under Zone.js, the handler
+   * execution) inside the Angular zone, so async work started inside a lifecycle
+   * hook is still zone-tracked. Under zoneless Angular it is a passthrough.
+   */
   return zone.run(() => {
     const unregisters = LIFECYCLES.filter((eventName) => typeof instance[eventName] === 'function').map((eventName) => {
-      const handler = (ev: any) => instance[eventName](ev.detail);
+      const handler = (ev: any) => {
+        instance[eventName](ev.detail);
+        /**
+         * Ionic lifecycle events (`ionViewWillEnter`, etc.) are dispatched from
+         * the web component via a native event listener, so under zoneless
+         * Angular nothing schedules change detection for state the hook mutates.
+         * Mark the view dirty explicitly. This is a no-op-or-better under Zone.js.
+         */
+        changeDetectorRef.markForCheck();
+      };
       element.addEventListener(eventName, handler);
       return () => element.removeEventListener(eventName, handler);
     });

packages/angular/package.json

@@ -60,6 +60,11 @@
     "rxjs": ">=7.5.0",
     "zone.js": ">=0.13.0"
   },
+  "peerDependenciesMeta": {
+    "zone.js": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@angular-devkit/core": "^21.0.0",
     "@angular-devkit/schematics": "^21.0.0",