This guide assumes that you have already updated your app to the latest version of Ionic 5. Make sure you have followed the Updating to Ionic 5 Guide before starting this guide.
For a complete list of breaking changes from Ionic 5 to Ionic 6, please refer to the breaking changes document in the Ionic Framework repository.
If you are using Ionic Angular Server, be sure to update that as well:
Developers must import and call setupIonicReact even if they are not setting custom config.
Refer to the React Config Documentation for more examples.
Then, upgrade all Vue CLI plugins:
Refer to the Testing section below for more information.
Remove any usage of the setupConfig function previously exported from @ionic/vue. Set your config when installing the IonicVue plugin instead. Refer to the Vue Config Documentation for more examples.
Rename the IonRouter type for useIonRouter to UseIonRouterResult.
Rename the IonKeyboardRef type for useKeyboard to UseKeyboardResult.
Rename any overlay event listeners to use the new format:
This applies to ion-action-sheet, ion-alert, ion-loading, ion-modal, ion-picker, ion-popover, and ion-toast.
Remove any usages of the placeholder, pickerOptions, pickerFormat, monthNames, monthShortNames, dayNames, and dayShortNames properties. ion-datetime now automatically formats the month names, day names, and time displayed inside of the component according to the language and region set on the device. Refer to the ion-datetime Localization Documentation for more information.
Remove any usages of the text and placeholder CSS Shadow Parts.
Remove any usages of the --padding-bottom, --padding-end, --padding-start, --padding-top, and --placeholder-color CSS Variables. To customize the padding on ion-datetime, you can use any of the padding CSS properties.
Remove any usage of the open method. To present the datetime in an overlay, place it inside of an ion-modal or an ion-popover component. Refer to the ion-datetime Usage Examples for more information.
Remove any usage of the displayFormat or displayTimezone properties. To parse the UTC string provided in the payload of the ionChange event, we recommend using date-fns. Refer to the ion-datetime Parsing Dates Documentation for examples.
Refer to the Datetime Migration Sample Application for more migration examples.
Ionic 6 now ships with Ionicons 6. Review the Ionicons 6 Breaking Changes Guide and make any necessary changes.
Ensure null is not passed in as a value to the placeholder property. We recommend using undefined instead.
ion-modal now uses the Shadow DOM. Update any styles targeting the internals of ion-modal to use either the ion-modal CSS Variables or the ion-modal CSS Shadow Parts:
ion-popover now uses the Shadow DOM. Update any styles targeting the internals of ion-popover to use either ion-popover CSS Variables or the ion-popover CSS Shadow Parts:
Remove any usage of the RadioChangeEventDetail interface.
Ensure null is not passed in as a value to the placeholder property. We recommend using undefined instead.
Ensure null is not passed in as a value to the placeholder property. We recommend using undefined instead.
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:
Ionic 6 now ships as ES Modules. ES Modules are supported in all major browsers and bring developer experience and code maintenance improvements. Developers testing with Jest will need to update their Jest configuration as Jest does not have full support for ES Modules as of Jest 27.
This update involves using Babel to compile Ionic's ES Modules down to the CommonJS (CJS) format, a format that Jest can understand. Once Jest ships support for ES Modules, this change will no longer be necessary. See https://github.com/facebook/jest/issues/9430 for
updates on ES Modules support in Jest.
If you are starting fresh with a new Ionic app, this configuration is done for you in our starter applications. For those with existing Ionic apps, follow the steps below to get Jest working with Ionic 6:
If you are using Ionic React or Ionic Vue, be sure to add the appropriate packages to the transformIgnorePatterns array. For Ionic React this includes @ionic/react and @ionic/react-router. For Ionic Vue this includes @ionic/vue and @ionic/vue-router.
For developers using Create React App (CRA), there is currently no way to update the transformIgnorePatterns in a Jest config file. This is a CRA restriction and not something Ionic has control over. We can, however, pass the transformIgnorePatterns directly into the react-scripts test command:
If you are still running into issues, here are a couple things to try:
Verify that @babel/preset-env is included in your project-wide configuration instead of your file-relative configuration. This typically means defining the Babel configuration in <project-root>/babel.config.json.
If you have a browserslist/test field in package.json file, make sure it is set to current node.
Be sure to review the Ionic 6 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 required user action are listed on this page.
If you need help upgrading, please post a thread on the Ionic Forum.