note
This guide assumes that you have already updated your app to the latest version of Ionic 7. Make sure you have followed the Upgrading to Ionic 7 Guide before starting this guide.
Breaking Changes
For a complete list of breaking changes from Ionic 7 to Ionic 8, please refer to the breaking changes document in the Ionic Framework repository.
Angular
Ionic 8 supports Angular 16+. Update to the latest version of Angular by following the Angular Update Guide.
Update to the latest version of Ionic 8:
npm install @ionic/angular@latest
If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well:
npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-toolkit@11
Note:
@ionic/angular-toolkit@11
requires a minimum of Angular 17. If you are still on Angular 16, then you may want to only update to to@ionic/angular-toolkit@10
instead.
- Update any
IonBackButtonDelegate
imports from@ionic/angular
to importIonBackButton
from@ionic/angular
instead.
React
- Ionic 8 supports React 17+. Update to the latest version of React:
npm install react@17 react-dom@17
- Update to the latest version of Ionic 8:
npm install @ionic/react@8 @ionic/react-router@8
Vue
- Ionic 8 supports Vue 3.0.6+. Update to the latest version of Vue:
npm install vue@^3.0.6 vue-router@^3.0.6
- Update to the latest version of Ionic 8:
npm install @ionic/vue@8 @ionic/vue-router@8
Core
- Update to the latest version of Ionic 8:
npm install @ionic/core@8
Recommended Changes
The following changes are not required to update to Ionic 8 as your application will continue to work. However, we recommend making the following changes to ensure you can use the new features in Ionic 8.
Light Palette
Previous versions defined a set of default color variables for the light palette 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;
/* ... */
}
In Ionic Framework version 8, these color variables are included as long as core.css
is imported. The color variables defined in theme/variables.scss
should be removed to avoid overriding the imported default variables and ensure the app is always using the latest palette.
Developers who are customizing this color palette can continue to keep the custom variables values, but any of the variables that use the default values should be removed.
You can read more about the new color palette in the Ionic v8 announcement.
Dark Palette
In previous versions, it was recommended to define the dark palette in the following way:
@media (prefers-color-scheme: dark) {
body {
/* global app variables */
}
.ios body {
/* global ios app variables */
}
.md body {
/* global md app variables */
}
}
In Ionic Framework version 8, the dark palette is being distributed via css files that can be imported. Below is an example of importing a dark palette file in Angular:
/* @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 is now applied to the :root
selector instead of the body
selector. The :root
selector represents the <html>
element and is identical to the selector html
, except that its specificity is higher.
While migrating to include the new dark palette files is unlikely to cause breaking changes, these new selectors can lead to unexpected overrides if custom CSS variables are being set on the body
element. We recommend updating any instances where global application variables are set to target the :root
selector instead.
For more information on the new dark palette files, refer to the Dark Mode documentation.
Step Color Tokens
To better support the high contrast palette in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of --ion-color-step-[number]
tokens.
Using the newly imported dark palette mentioned above will also import these new step color tokens. However, developers will need to update any step color tokens that were manually defined in an application.
--ion-color-step-[number]
usages for background color can be migrated by renaming the token to --ion-background-color-step-[number]
.
Before:
button { background: var(--ion-color-step-400); }
After:
button { background: var(--ion-background-color-step-400); }
--ion-color-step-[number]
usages for text color can be migrated by renaming the token to --ion-text-color-step-[number]
and subtracting 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 has been updated to generate text and background color stepped variables.
Dynamic Font
The core.css
file has been updated to enable dynamic font scaling by default.
The --ion-default-dynamic-font
variable has been removed and replaced with --ion-dynamic-font
.
Developers who had previously chosen dynamic font scaling by activating it in their global stylesheets can revert to the default setting by removing their custom CSS. In doing so, their application will seamlessly continue utilizing dynamic font scaling as it did before. It's essential to note that altering the font-size of the html element should be avoided, as it may disrupt the proper functioning of dynamic font scaling.
Developers who want to disable dynamic font scaling can set --ion-dynamic-font: initial;
in their global stylesheets. However, this is not recommended because it may introduce accessibility challenges for users who depend on enlarged font sizes.
For more information on the dynamic font, refer to the Dynamic Font Scaling documentation.
(Angular Only) angular.json
CSS import order
The angular.json
file currently imports src/theme/variables.scss
before importing src/global.scss
. This may cause the incorrect styles to be applied when customizing the new Dark Palette changes.
We recommend importing the src/global.scss
file first instead:
Before:
"styles": ["src/theme/variables.scss", "src/global.scss"],
After:
"styles": ["src/global.scss", "src/theme/variables.scss"],
Browser Support
The list of browsers that Ionic supports has changed. Review the Browser Support Guide to ensure you are deploying apps to supported browsers.
If you have a browserslist
or .browserslistrc
file, update it with the following content:
Chrome >=89
ChromeAndroid >=89
Firefox >=75
Edge >=89
Safari >=15
iOS >=15
Checkbox
- Migrate any remaining instances of Checkbox to use the modern form control syntax. Additionally, remove any usages of the
legacy
property as the legacy form control syntax has been removed.
Input
- Remove any usages of the
size
property. CSS should be used to specify the visible width of the input instead. - Remove any usages of the
accept
property. - Migrate any remaining instances of Input to use the modern form control syntax. Additionally, remove any usages of the
legacy
property as the legacy form control syntax has been removed.
Item
- Remove any usages of the
counter
orcounterFormatter
properties. Use the properties of the same names onion-input
andion-textarea
instead. - Remove any usages of the
helper
orerror
slots. Use thehelperText
anderrorText
properties onion-input
andion-textarea
instead. - Remove any usages of the
fill
orshape
properties. Use the properties of the same names onion-input
,ion-textarea
, andion-select
instead.
Nav
- Update any usages of
getLength
toawait
the call before accessing the returned value as this method now returnsPromise<number>
instead ofnumber
.
Picker
- Ionic 8 now ships with an inline
ion-picker
component. Developers who wish to continue using the legacy picker should update anyion-picker
usages toion-picker-legacy
. ThepickerController
import remains unchanged. Note that theion-picker-legacy
component will be removed in an upcoming major release of Ionic. Refer to the Picker documentation for usage information.
Toast
- Remove any usages of the
cssClass
property fromToastButton
. Thebutton
CSS Shadow Part should be used instead.
Radio
- Migrate any remaining instances of Radio to use the modern form control syntax. Additionally, remove any usages of the
legacy
property as the legacy form control syntax has been removed.
Select
- Migrate any remaining instances of Select to use the modern form control syntax. Additionally, remove any usages of the
legacy
property as the legacy form control syntax has been removed.
Textarea
- Migrate any remaining instances of Textarea to use the modern form control syntax. Additionally, remove any usages of the
legacy
property as the legacy form control syntax has been removed.
Toggle
- Migrate any remaining instances of Toggle to use the modern form control syntax. Additionally, remove any usages of the
legacy
property as the legacy form control syntax has been removed.
Need Help Upgrading?
Be sure to look at the Ionic 8 Breaking Changes Guide. There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that require user action are listed on this page.
If you need help upgrading, please post a thread on the Ionic Forum.