Skip to content

Commit acadcf5

Browse files
liamdebeasiliamdebeasi
authored
docs(updating): add v8 migration guide (#3475)
1 parent 4d24294 commit acadcf5

File tree

3 files changed

+185
-3
lines changed

3 files changed

+185
-3
lines changed

‎docs/updating/6-0.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This guide assumes that you have already updated your app to the latest version
99
:::
1010

1111
:::info Breaking Changes
12-
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.
12+
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.
1313
:::
1414

1515
## Getting Started
@@ -473,6 +473,6 @@ If you are still running into issues, here are a couple things to try:
473473

474474
## Need Help Upgrading?
475475

476-
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.
476+
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.
477477

478478
If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/).

‎docs/updating/8-0.md

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: Updating to v8
3+
---
4+
5+
# Updating from Ionic 7 to 8
6+
7+
:::note
8+
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.
9+
:::
10+
11+
:::info Breaking Changes
12+
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.
13+
:::
14+
15+
## Getting Started
16+
17+
### Angular
18+
19+
1. Ionic 8 supports Angular 16+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/).
20+
21+
2. Update to the latest version of Ionic 8:
22+
23+
```shell
24+
npm install @ionic/angular@next
25+
```
26+
27+
If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to update those as well:
28+
29+
```shell
30+
npm install @ionic/angular@next @ionic/angular-server@next @ionic/angular-toolkit@11
31+
```
32+
33+
> 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.
34+
35+
3. Update any `IonBackButtonDelegate` imports from `@ionic/angular` to import `IonBackButton` from `@ionic/angular` instead.
36+
37+
### React
38+
39+
1. Ionic 8 supports React 17+. Update to the latest version of React:
40+
41+
```shell
42+
npm install react@latest react-dom@latest
43+
```
44+
45+
2. Update to the latest version of Ionic 8:
46+
47+
```shell
48+
npm install @ionic/react@next @ionic/react-router@next
49+
```
50+
51+
### Vue
52+
53+
1. Ionic 7 supports Vue 3.0.6+. Update to the latest version of Vue:
54+
55+
```shell
56+
npm install vue@latest vue-router@latest
57+
```
58+
59+
3. Update to the latest version of Ionic 8:
60+
61+
```shell
62+
npm install @ionic/vue@next @ionic/vue-router@next
63+
```
64+
65+
### Core
66+
67+
1. Update to the latest version of Ionic 8:
68+
69+
```shell
70+
npm install @ionic/core@next
71+
```
72+
73+
## Recommended Changes
74+
75+
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.
76+
77+
### Dark Theme
78+
79+
In previous versions, it was recommended to define the dark theme in the following way:
80+
81+
```css
82+
@media (prefers-color-scheme: dark) {
83+
body {
84+
/* global app variables */
85+
}
86+
87+
.ios body {
88+
/* global ios app variables */
89+
}
90+
91+
.md body {
92+
/* global md app variables */
93+
}
94+
}
95+
```
96+
97+
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:
98+
99+
```css
100+
/* @import '@ionic/angular/css/themes/dark.always.css'; */
101+
/* @import "@ionic/angular/css/themes/dark.class.css"; */
102+
@import '@ionic/angular/css/themes/dark.system.css';
103+
```
104+
105+
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 `<html>` element and is identical to the selector `html`, except that its specificity is higher.
106+
107+
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.
108+
109+
For more information on the new dark theme files, refer to the [Dark Mode documentation](../theming/dark-mode).
110+
111+
### Dynamic Font
112+
113+
The `core.css` file has been updated to enable dynamic font scaling by default.
114+
115+
The `--ion-default-dynamic-font` variable has been removed and replaced with `--ion-dynamic-font`.
116+
117+
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.
118+
119+
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.
120+
121+
For more information on the dynamic font, refer to the [Dynamic Font Scaling documentation](../layout/dynamic-font-scaling).
122+
123+
## Required Changes
124+
125+
### Browser Support
126+
127+
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.
128+
129+
If you have a `browserslist` or `.browserslistrc` file, update it with the following content:
130+
131+
```
132+
Chrome >=89
133+
ChromeAndroid >=89
134+
Firefox >=75
135+
Edge >=89
136+
Safari >=15
137+
iOS >=15
138+
```
139+
140+
### Checkbox
141+
142+
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.
143+
144+
### Input
145+
146+
1. Remove any usages of the `size` property. CSS should be used to specify the visible width of the input instead.
147+
2. Remove any usages of the `accept` property.
148+
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.
149+
150+
### Nav
151+
152+
1. Update any usages of `getLength` to `await` the call before accessing the returned value as this method now returns `Promise<number>` instead of `number`.
153+
154+
### Picker
155+
156+
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.
157+
158+
### Toast
159+
160+
1. Remove any usages of the `cssClass` property from `ToastButton`. The `button` CSS Shadow Part should be used instead.
161+
162+
### Radio
163+
164+
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.
165+
166+
### Select
167+
168+
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.
169+
170+
### Textarea
171+
172+
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.
173+
174+
### Toggle
175+
176+
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.
177+
178+
## Need Help Upgrading?
179+
180+
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.
181+
182+
If you need help upgrading, please post a thread on the [Ionic Forum](https://forum.ionicframework.com/).

‎sidebars.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ module.exports = {
1010
type: 'category',
1111
label: 'Upgrade Guides',
1212
collapsed: false,
13-
items: ['updating/7-0', 'updating/6-0', 'updating/5-0', 'updating/4-0'],
13+
items: ['updating/8-0', 'updating/7-0', 'updating/6-0', 'updating/5-0', 'updating/4-0'],
1414
},
1515
{
1616
type: 'category',

0 commit comments

Comments
 (0)