From db525bfb4925be7d5f59ba66f4ed727caf879a31 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 14:07:19 -0500 Subject: [PATCH 01/14] docs(updating): v6 references correct archive --- docs/updating/6-0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/updating/6-0.md b/docs/updating/6-0.md index 321daf2f0e3..d9f7ef2cec6 100644 --- a/docs/updating/6-0.md +++ b/docs/updating/6-0.md @@ -9,7 +9,7 @@ This guide assumes that you have already updated your app to the latest version ::: :::info Breaking Changes -For a **complete list of breaking changes** from Ionic 5 to Ionic 6, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md) in the Ionic Framework repository. +For a **complete list of breaking changes** from Ionic 5 to Ionic 6, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING_ARCHIVE/v6.md) in the Ionic Framework repository. ::: ## Getting Started @@ -473,6 +473,6 @@ If you are still running into issues, here are a couple things to try: ## Need Help Upgrading? -Be sure to look at the [Ionic 6 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that required user action are listed on this page. +Be sure to look at the [Ionic 6 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING_ARCHIVE/v6.md). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that required user action are listed on this page. If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/). From 13cde51b98fa8b907fcdd173241a1fccac89b37a Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 15:59:35 -0500 Subject: [PATCH 02/14] add migration guide --- docs/updating/8-0.md | 182 +++++++++++++++++++++++++++++++++++++++++++ sidebars.js | 2 +- 2 files changed, 183 insertions(+), 1 deletion(-) create mode 100644 docs/updating/8-0.md diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md new file mode 100644 index 00000000000..a7f54975b34 --- /dev/null +++ b/docs/updating/8-0.md @@ -0,0 +1,182 @@ +--- +title: Updating to v8 +--- + +# Updating from Ionic 7 to 8 + +:::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](./7-0) before starting this guide. +::: + +:::info Breaking Changes +For a **complete list of breaking changes** from Ionic 7 to Ionic 8, please refer to [the breaking changes document](https://github.com/ionic-team/ionic-framework/blob/feature-8.0/BREAKING.md#version-8x) in the Ionic Framework repository. +::: + +## Getting Started + +### Angular + +1. Ionic 8 supports Angular 16+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/). + +2. Update to the latest version of Ionic 8: + +```shell +npm install @ionic/angular@8 +``` + +If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well: + +```shell +npm install @ionic/angular@8 @ionic/angular-server@8 @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. + +3. Update any `IonBackButtonDelegate` imports from `@ionic/angular` to import `IonBackButton` from `@ionic/angular` instead. + +### React + +1. Ionic 8 supports React 17+. Update to the latest version of React: + +```shell +npm install react@latest react-dom@latest +``` + +2. Update to the latest version of Ionic 8: + +```shell +npm install @ionic/react@8 @ionic/react-router@8 +``` + +### Vue + +1. Ionic 7 supports Vue 3.0.6+. Update to the latest version of Vue: + +```shell +npm install vue@latest vue-router@latest +``` + +3. Update to the latest version of Ionic 8: + +```shell +npm install @ionic/vue@8 @ionic/vue-router@8 +``` + +### Core + +1. Update to the latest version of Ionic 8: + +```shell +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. + +### Dark Theme + +In previous versions, it was recommended to define the dark theme in the following way: + +```css +@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 theme is being distributed via css files that can be imported. Below is an example of importing a dark theme file in Angular: + +```css +/* @import '@ionic/angular/css/themes/dark.always.css'; */ +/* @import "@ionic/angular/css/themes/dark.class.css"; */ +@import "@ionic/angular/css/themes/dark.system.css"; +``` + +Notice that the dark theme is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `` element and is identical to the selector `html`, except that its specificity is higher. + +While migrating to include the new dark theme 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 theme files, refer to the [Dark Mode documentation](../theming/dark-mode). + +### 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](../layout/dynamic-font-scaling). + +## Updating Your Code + +### Browser Support + +The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) 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 + +1. Migrate any remaining instances of Checkbox to use the [modern form control syntax](../api/checkbox#migrating-from-legacy-checkbox-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. + +### Input + +1. Remove any usages of the `size` property. CSS should be used to specify the visible width of the input instead. +2. Remove any usages of the `accept` property. +3. Migrate any remaining instances of Input to use the [modern form control syntax](../api/input#migrating-from-legacy-input-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. + +### Nav + +1. Update any usages of `getLength` to `await` the call before accessing the returned value as this method now returns `Promise` instead of `number`. + +### Picker + +1. Ionic 8 now ships with an inline `ion-picker` component. Developers who wish to continue using the legacy picker should update any `ion-picker` usages to `ion-picker-legacy`. The `pickerController` import remains unchanged. + +### Toast + +1. Remove usages of the `cssClass` property from `ToastButton`. The `button` CSS Shadow Part should be used instead. + +### Radio + +1. Migrate any remaining instances of Radio to use the [modern form control syntax](../api/radio#migrating-from-legacy-radio-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. + +### Select + +1. Migrate any remaining instances of Select to use the [modern form control syntax](../api/select#migrating-from-legacy-select-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. + +### Textarea + +1. Migrate any remaining instances of Textarea to use the [modern form control syntax](../api/textarea#migrating-from-legacy-textarea-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. + +### Toggle + +1. Migrate any remaining instances of Toggle to use the [modern form control syntax](../api/toggle#migrating-from-legacy-toggle-syntax). Additionally, remove the 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](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-8x). 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](https://forum.ionicframework.com/). diff --git a/sidebars.js b/sidebars.js index fc7327499f5..e9094c63ef3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -10,7 +10,7 @@ module.exports = { type: 'category', label: 'Upgrade Guides', collapsed: false, - items: ['updating/7-0', 'updating/6-0', 'updating/5-0', 'updating/4-0'], + items: ['updating/8-0', 'updating/7-0', 'updating/6-0', 'updating/5-0', 'updating/4-0'], }, { type: 'category', From 15533bc46ae3f2cae05a63e0bcd51adca3dc8dc3 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:01:12 -0500 Subject: [PATCH 03/14] use next tag --- docs/updating/8-0.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index a7f54975b34..ee8ac9db2f3 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -21,13 +21,13 @@ For a **complete list of breaking changes** from Ionic 7 to Ionic 8, please refe 2. Update to the latest version of Ionic 8: ```shell -npm install @ionic/angular@8 +npm install @ionic/angular@next ``` If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well: ```shell -npm install @ionic/angular@8 @ionic/angular-server@8 @ionic/angular-toolkit@11 +npm install @ionic/angular@next @ionic/angular-server@next @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. @@ -45,7 +45,7 @@ npm install react@latest react-dom@latest 2. Update to the latest version of Ionic 8: ```shell -npm install @ionic/react@8 @ionic/react-router@8 +npm install @ionic/react@next @ionic/react-router@next ``` ### Vue @@ -59,7 +59,7 @@ npm install vue@latest vue-router@latest 3. Update to the latest version of Ionic 8: ```shell -npm install @ionic/vue@8 @ionic/vue-router@8 +npm install @ionic/vue@next @ionic/vue-router@next ``` ### Core @@ -67,7 +67,7 @@ npm install @ionic/vue@8 @ionic/vue-router@8 1. Update to the latest version of Ionic 8: ```shell -npm install @ionic/core@8 +npm install @ionic/core@next ``` ## Recommended Changes From a1a246829472ccc357553726ae956c83f9cbd5b1 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:18:19 -0500 Subject: [PATCH 04/14] lint --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index ee8ac9db2f3..47c4f309a5f 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -99,7 +99,7 @@ In Ionic Framework version 8, the dark theme is being distributed via css files ```css /* @import '@ionic/angular/css/themes/dark.always.css'; */ /* @import "@ionic/angular/css/themes/dark.class.css"; */ -@import "@ionic/angular/css/themes/dark.system.css"; +@import '@ionic/angular/css/themes/dark.system.css'; ``` Notice that the dark theme is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `` element and is identical to the selector `html`, except that its specificity is higher. From e7763eb3ccf2a67fba7a792c73fa15e20971da0f Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:17 -0500 Subject: [PATCH 05/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 47c4f309a5f..b4c63abd222 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -139,7 +139,7 @@ iOS >=15 ### Checkbox -1. Migrate any remaining instances of Checkbox to use the [modern form control syntax](../api/checkbox#migrating-from-legacy-checkbox-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. +1. Migrate any remaining instances of Checkbox to use the [modern form control syntax](../api/checkbox#migrating-from-legacy-checkbox-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed. ### Input From fa435426eb05f3bc847f8430de0ae43594a0eb13 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:25 -0500 Subject: [PATCH 06/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index b4c63abd222..32b85e785f7 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -145,7 +145,7 @@ iOS >=15 1. Remove any usages of the `size` property. CSS should be used to specify the visible width of the input instead. 2. Remove any usages of the `accept` property. -3. Migrate any remaining instances of Input to use the [modern form control syntax](../api/input#migrating-from-legacy-input-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. +3. Migrate any remaining instances of Input to use the [modern form control syntax](../api/input#migrating-from-legacy-input-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed. ### Nav From 571c068efb9569287cbc478f015659704fd6e678 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:31 -0500 Subject: [PATCH 07/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 32b85e785f7..3edaf2cc2c4 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -157,7 +157,7 @@ iOS >=15 ### Toast -1. Remove usages of the `cssClass` property from `ToastButton`. The `button` CSS Shadow Part should be used instead. +1. Remove any usages of the `cssClass` property from `ToastButton`. The `button` CSS Shadow Part should be used instead. ### Radio From 9a0f321170db1658316d5d113e2a9699d7b1710f Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:35 -0500 Subject: [PATCH 08/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 3edaf2cc2c4..b6dc1b19ce7 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -161,7 +161,7 @@ iOS >=15 ### Radio -1. Migrate any remaining instances of Radio to use the [modern form control syntax](../api/radio#migrating-from-legacy-radio-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. +1. Migrate any remaining instances of Radio to use the [modern form control syntax](../api/radio#migrating-from-legacy-radio-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed. ### Select From 62fb09c1774ef2ec7f90b17efdbe78cae5973ef6 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:41 -0500 Subject: [PATCH 09/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index b6dc1b19ce7..6a8204b05b1 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -165,7 +165,7 @@ iOS >=15 ### Select -1. Migrate any remaining instances of Select to use the [modern form control syntax](../api/select#migrating-from-legacy-select-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. +1. Migrate any remaining instances of Select to use the [modern form control syntax](../api/select#migrating-from-legacy-select-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed. ### Textarea From ce8f10b153d44473d2b4eb272ca4c585cf6718fd Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:46 -0500 Subject: [PATCH 10/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 6a8204b05b1..0cfa67854fc 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -169,7 +169,7 @@ iOS >=15 ### Textarea -1. Migrate any remaining instances of Textarea to use the [modern form control syntax](../api/textarea#migrating-from-legacy-textarea-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. +1. Migrate any remaining instances of Textarea to use the [modern form control syntax](../api/textarea#migrating-from-legacy-textarea-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed. ### Toggle From 8bc07dce512371c5991402e8deb759caf0caa881 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:23:51 -0500 Subject: [PATCH 11/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 0cfa67854fc..df91d1728b8 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -173,7 +173,7 @@ iOS >=15 ### Toggle -1. Migrate any remaining instances of Toggle to use the [modern form control syntax](../api/toggle#migrating-from-legacy-toggle-syntax). Additionally, remove the any usages of the `legacy` property as the legacy form control syntax has been removed. +1. Migrate any remaining instances of Toggle to use the [modern form control syntax](../api/toggle#migrating-from-legacy-toggle-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed. ## Need Help Upgrading? From ec65471d835fc22db444c43fbd63181d41bd3a59 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:24:20 -0500 Subject: [PATCH 12/14] Update docs/updating/8-0.md Co-authored-by: Brandy Carney --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index df91d1728b8..4796b6279a9 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -102,7 +102,7 @@ In Ionic Framework version 8, the dark theme is being distributed via css files @import '@ionic/angular/css/themes/dark.system.css'; ``` -Notice that the dark theme is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `` element and is identical to the selector `html`, except that its specificity is higher. +The dark theme is now applied to the `:root` selector instead of the `body` selector. The [`:root`](https://developer.mozilla.org/en-US/docs/Web/CSS/:root) selector represents the `` element and is identical to the selector `html`, except that its specificity is higher. While migrating to include the new dark theme 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. From 637b3b62e98061fa98fb301a34863c0da75e6ae3 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 16:25:08 -0500 Subject: [PATCH 13/14] fix wording --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 4796b6279a9..1dc1c3f0736 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -120,7 +120,7 @@ Developers who want to disable dynamic font scaling can set `--ion-dynamic-font: For more information on the dynamic font, refer to the [Dynamic Font Scaling documentation](../layout/dynamic-font-scaling). -## Updating Your Code +## Required Changes ### Browser Support From 7bdf9f2359c2406e0a85ce6eab672747093e0bf0 Mon Sep 17 00:00:00 2001 From: Liam DeBeasi Date: Tue, 27 Feb 2024 17:55:36 -0500 Subject: [PATCH 14/14] note that legacy picker will be removed --- docs/updating/8-0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/updating/8-0.md b/docs/updating/8-0.md index 1dc1c3f0736..bcbe2147e71 100644 --- a/docs/updating/8-0.md +++ b/docs/updating/8-0.md @@ -153,7 +153,7 @@ iOS >=15 ### Picker -1. Ionic 8 now ships with an inline `ion-picker` component. Developers who wish to continue using the legacy picker should update any `ion-picker` usages to `ion-picker-legacy`. The `pickerController` import remains unchanged. +1. Ionic 8 now ships with an inline `ion-picker` component. Developers who wish to continue using the legacy picker should update any `ion-picker` usages to `ion-picker-legacy`. The `pickerController` import remains unchanged. Note that the `ion-picker-legacy` component will be removed in an upcoming major release of Ionic. ### Toast