Updating to v9 | Ionic Framework

This guide assumes that you have already updated your app to the latest version of Ionic 8. Make sure you have followed the Upgrading to Ionic 8 Guide before starting this guide.
For a complete list of breaking changes from Ionic 8 to Ionic 9, please refer to the breaking changes document in the Ionic Framework repository.
Before manually working through the changes below, you can run the Ionic migration tool. It scans your app, automatically applies the breaking changes that can be safely migrated, and prints a checklist of the remaining updates that require manual work. Each item includes the affected file, line number, and a link to the corresponding section of this guide. Because the tool reads your framework and version from package.json, it only applies migrations that are relevant to your app.
Commit your work first. The tool writes changes in place and refuses to run on a dirty working tree, or a project without git, unless you pass --force, so git is your undo.
After a run it prints a summary of what it fixed and what is left for you, formats the changed files with your project's Prettier, and, if it applied anything, reinstalls dependencies so node_modules matches the version bump.
Run npx @ionic/migrate --help for the full list.
The tool is single-shot. Once it bumps your @ionic/* version, a re-run detects the new major and does nothing, so run it once per major upgrade and review the diff before committing.
Ionic 9 supports Angular 18 through 22. Angular 16 and 17 are no longer supported. Update to a supported version of Angular by following the Angular Update Guide.
Update to the latest version of Ionic 9:
If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well:
Ionic 9 supports zoneless change detection. Angular 21 made zoneless the default, so a new Ionic 9 app on Angular 21 or later 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 for the patterns Ionic apps use.
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.
If you prefer to keep using Zone.js on Angular 21 or later, opt back in with provideZoneChangeDetection().
For standalone applications, add the provider to bootstrapApplication:
For NgModule applications, pass it as applicationProviders on bootstrapModule(). Angular does not allow provideZoneChangeDetection() inside an NgModule's providers array:
Either way, also confirm zone.js is still loaded, since Angular 21 and later default scaffolds omit it. Add it back through whichever polyfills setup your project uses.
If angular.json lists polyfills as an array, include zone.js:
If your project uses a polyfills file instead (for example, Ionic starters set "polyfills": "src/polyfills.ts"), import it there:
Angular 22 changes the default change detection strategy to OnPush for components that don't declare one. Combined with the zoneless default above, component state you mutate as a plain field from an Ionic lifecycle hook (ionViewWillEnter, and so on) no longer re-renders on its own.
Run ng update when upgrading to Angular 22; it migrates your existing components to eager change detection and preserves the previous behavior. To write OnPush-ready components instead, set the state through a signal or call ChangeDetectorRef.markForCheck() in the hook:
Ionic's own Angular components already declare OnPush, so they are unaffected. Angular 18 through 21 keep the eager default and require no change.
Ionic 9 supports TypeScript 5.4 or later, matching the minimum for Angular 18. Angular 21 requires TypeScript 5.9 or later, and Angular 22 requires TypeScript 6.0 or later.
Angular 22 raises the minimum Node.js version to ^22.22.3 || ^24.15.0 || ^26.0.0. Angular 18 through 21 are unaffected.
Ionic 9 makes standalone components the default import path. Change lazy-loaded component imports from @ionic/angular to @ionic/angular/lazy. Change standalone component imports from @ionic/angular/standalone to @ionic/angular.
IonicModule is deprecated in Ionic 9 and will be removed in a future major version. It remains fully functional, so no immediate action is required. When you are ready, migrate to provideIonicAngular(), which works in both standalone and NgModule-based apps. Refer to Migrating from Modules to Standalone.
Remove the ~ prefix from @ionic/angular CSS imports. Angular's current build pipeline no longer supports the webpack-loader prefix:
If your app uses TypeScript moduleResolution: "node" (classic), imports from subpaths such as @ionic/angular/lazy can fail to resolve. Set moduleResolution to "bundler" in your tsconfig.json. Apps created with ng new on Angular 17 or later already use this.
The @ionic/react package requires TypeScript 5.4 or later. Its type definitions use NoInfer, which TypeScript added in 5.4.
The useIonModal and useIonPopover hooks now type componentProps against the component they are given, instead of accepting any. Passing props that do not match the component is a compile error, and componentProps is required when the component declares required props:
Omitting componentProps altogether rules out the component signature, so TypeScript reports a mismatch against the JSX element signature rather than naming the missing prop.
This surfaces existing mistakes at build time rather than at runtime, so an app that was passing incorrect props will see new type errors. Fix the call sites to