diff --git a/docs/api/picker.md b/docs/api/picker.md index a78be5cf151..276cc58cd1e 100644 --- a/docs/api/picker.md +++ b/docs/api/picker.md @@ -48,6 +48,76 @@ Pickers can be displayed inside of overlays, such as `ion-modal` to create a pic import ModalExample from '@site/static/usage/v8/picker/modal/index.md'; + +## Migrating from the Legacy Picker + +The new picker syntax brings many improvements such as better performance and the ability to render a picker inline with your page content. It also allows developers to write the picker columns and column options directly in their template. As part of this, developers gain the ability to conditionally render columns/options, dynamically add columns/options, and more! + +The new picker syntax is found in a separate component, so developers can continue to use the legacy picker if they wish. + +Use the following steps to migrate from `ion-picker-legacy` to `ion-picker`. + +### Updating Imports + +1. Update any usages for `ion-picker-legacy` to `ion-picker`. This includes component usages in a template as well as component imports. + +```diff +- import { IonPickerLegacy } from '@ionic/react'; ++ import { IonPicker } from '@ionic/react'; +``` + +```diff +- ++ +``` + +### Migrating Picker + +The following table shows how each API for `ion-picker-legacy` maps to the new `ion-picker`. + +**Properties** + +Note: A majority of the properties here relate to overlays and not the picker itself. As a result, much of the functionality here is duplicated by a modal or a popover. + +| Name | Alternative | +| - | - | +| `mode` | No change. | +| `buttons` | See [the Picker in a Modal example](#picker-in-modal) | +| `columns` | See [Adding Columns](#adding-columns) | +| `cssClass` | Use the `class` attribute (or `className` if you are using React). | +| `duration` | Use a `setTimeout` to dismiss the modal that presents the picker. See [the Picker in a Modal example](#picker-in-modal) for how to show a picker in a modal. Note: We do not recommend using this as the duration may not give users enough time to select an option. | +| `enterAnimation` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `leaveAnimation` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `htmlAttributes` | Set the attributes directly on `ion-picker`. | +| `isOpen` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `keyboardClose` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `animated` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `backdropDismiss` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `showBackdrop` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | +| `trigger` | Use the property of the same name on a modal or a popover if using the picker in an overlay. | + +### Adding Columns + +2. Remove the `columns` property in favor of using the [ion-picker-column](./picker-column) component. Any options within each column can be rendered using the [ion-picker-column-option](./picker-column-option) component. + +The following table shows how each key in [legacy PickerColumn interface](./picker-legacy#pickercolumn) maps to the new [ion-picker-column](./picker-column). + +| `PickerColumn` Key | `ion-picker-column` Equivalent | +| - | - | +| `name` | Not needed. | +| `align` | Use CSS to change the alignent of each `ion-picker-column`. However, the new picker has additional logic to correctly position each column within the picker, so most developers will not need to change anything. | +| `selectedIndex` | Use the `value` property. | +| `prevSelected` | Not needed. This was only used for internal record-keeping. | +| `prefix` | Use the [`prefix` slot](#prefix--suffix-content). | +| `suffix` | Use the [`suffix` slot](#prefix--suffix-content). | +| `options` | Use `ion-picker-column-option` inside of `ion-picker-column. | +| `cssClass` | Use the `class` attribute (or `className` if you are using React). | +| `columnWidth` | Use CSS and target `ion-picker-column` to change its width. | +| `prefixWidth` | Use CSS and target the content in the `prefix` slot to change its width. | +| `suffixWidth` | Use CSS and target the content in the `suffix` slot to change its width. | +| `options` | Use CSS and target `ion-picker-column-option` to change its width. | + +### Adding Options ## Properties 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/). 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',