Angular Upgrade Guide: Migrating from Ionic 7 to Ionic 8

This guide is specifically tailored for Angular developers looking to upgrade their Ionic 7 applications to Ionic 8. Before proceeding, ensure your application is already updated to the latest version of Ionic 7. If not, please follow the Upgrading to Ionic 7 Guide first.

For a comprehensive list of all changes, including breaking changes from Ionic 7 to Ionic 8, refer to the official breaking changes document in the Ionic Framework repository.

Getting Started with Angular Ionic 8 Upgrade

Follow these steps to upgrade your Angular Ionic application to Ionic 8:

1. Update Angular: Ionic 8 requires Angular 16 or higher. It’s highly recommended to update to the latest Angular version to benefit from the newest features and improvements. Use the Angular Update Guide to perform this update. This step is crucial for compatibility and leveraging the best performance in Ionic 8.

2. Update Ionic Angular Packages: Upgrade to the latest version of Ionic 8 packages using npm. Run the following command in your project directory:

npm install @ionic/angular@latest

If you are utilizing Ionic Angular Server and Ionic Angular Toolkit, update them as well to ensure compatibility:

npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-toolkit@latest

Note: @ionic/angular-toolkit@latest is recommended for Angular 17 and above. If you are using Angular 16, consider updating to @ionic/angular-toolkit@10 for compatibility. Keeping your toolkit aligned with your Angular version is important for a smooth upgrade process.

3. Update IonBackButtonDelegate Imports: In your Angular components, replace any imports of IonBackButtonDelegate from @ionic/angular with IonBackButton from @ionic/angular.

Recommended Changes for Ionic 8 Angular Apps

The following adjustments are recommended but not strictly required for the upgrade. Implementing these will allow you to take full advantage of Ionic 8’s new features and ensure optimal performance.

Adopt the New Light Palette

Ionic 8 introduces an updated default light color palette. Previous Ionic versions defined default color variables in theme/variables.scss.

/** Ionic CSS Variables **/
:root {
  /** primary **/
  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  /* ... */
}

With Ionic 8, these variables are included when core.css is imported. To avoid conflicts and ensure you’re using the latest palette, remove these default color variable definitions from theme/variables.scss. If you have custom color values, retain those, but remove any variables using default values to align with Ionic 8’s new palette.

Learn more about the new color palette in the Ionic v8 announcement.

Migrate to the Enhanced Dark Palette

Previously, defining the dark palette often involved media queries in your CSS:

@media (prefers-color-scheme: dark) {
  body {
    /* global app variables */
  }
  .ios body {
    /* global ios app variables */
  }
  .md body {
    /* global md app variables */
  }
}

Ionic 8 simplifies this by distributing dark palette via CSS files that you can import. Here’s how to import a dark palette file in your Angular Ionic app:

/* @import '@ionic/angular/css/palettes/dark.always.css'; */
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
@import '@ionic/angular/css/palettes/dark.system.css';

The dark palette now applies to the :root selector instead of body. While this migration is unlikely to cause immediate issues, it’s best practice to update any custom CSS variables currently targeting the body element to target :root instead to prevent potential overrides.

For detailed information on the new dark palette files, see the Dark Mode documentation.

Update to Step Color Tokens

Ionic 8 introduces separate step color tokens for text and background colors to enhance high contrast palette support. Previously, --ion-color-step-[number] controlled both.

Importing the new dark palette will automatically include these new tokens. If you manually defined step color tokens, you’ll need to update them.

For background colors, rename --ion-color-step-[number] to --ion-background-color-step-[number].

Before:

button { background: var(--ion-color-step-400); }

After:

button { background: var(--ion-background-color-step-400); }

For text colors, rename --ion-color-step-[number] to --ion-text-color-step-[number] and subtract the number from 1000.

Before:

button { color: var(--ion-color-step-400); }

After:

button { color: var(--ion-text-color-step-600); /* 1000 - 400 = 600 */ }

The stepped color generator is updated to generate these new text and background color stepped variables.

Leverage Dynamic Font Scaling

Ionic 8’s core.css enables dynamic font scaling by default.

The --ion-default-dynamic-font variable is removed and replaced with --ion-dynamic-font.

If you previously enabled dynamic font scaling manually, you can revert to the default behavior by removing your custom CSS. Dynamic font scaling will continue to function as before. Avoid altering the font-size of the html element as it can interfere with dynamic font scaling.

To disable dynamic font scaling, set --ion-dynamic-font: initial; in your global stylesheets. However, disabling this feature is not recommended due to potential accessibility issues for users who rely on larger font sizes.

For more information, consult the Dynamic Font Scaling documentation.

(Angular Specific) Adjust angular.json CSS Import Order

In your angular.json file, the current import order might load src/theme/variables.scss before src/global.scss. This can lead to styling issues with the new Dark Palette.

It’s recommended to import src/global.scss first.

Before:

"styles": ["src/theme/variables.scss", "src/global.scss"],

After:

"styles": ["src/global.scss", "src/theme/variables.scss"],

Required Changes for Ionic 8 Angular Upgrade

These changes are mandatory to ensure your Angular Ionic 8 application functions correctly.

Update Browser Support Configuration

Ionic 8 has updated its browser support list. Review the Browser Support Guide to confirm compatibility with your target browsers.

Update your browserslist or .browserslistrc file with the following:

Chrome >=89
ChromeAndroid >=89
Firefox >=75
Edge >=89
Safari >=15
iOS >=15

Input Component Updates

1. Remove size Property: The size property is deprecated. Use CSS to control input width.
2. Remove accept Property: The accept property is no longer supported.
3. Modern Form Control Syntax: Migrate all Input components to the modern form control syntax. Remove any usage of the legacy property as legacy syntax is removed.

Item Component Updates

1. Counter Properties: Remove counter and counterFormatter properties from ion-item. Use these properties directly on ion-input and ion-textarea.
2. Helper and Error Slots: Remove helper and error slots. Use helperText and errorText properties on ion-input and ion-textarea.
3. Fill and Shape Properties: Remove fill and shape properties from ion-item. Apply these properties to ion-input, ion-textarea, and ion-select.

Nav Component Updates

1. getLength Method: Update usages of getLength to await the call as it now returns a Promise instead of a number.

Toast Component Updates

1. cssClass Property in ToastButton: Remove cssClass property from ToastButton. Use the button CSS Shadow Part instead for styling.

Need Help Upgrading Your Angular Ionic App?

Refer to the Ionic 8 Breaking Changes Guide for a complete list of changes. If you require further assistance, post your questions on the Ionic Forum.