Good news everyone, Ionic 5 is finally out but this might also trigger some internal fear when you remember the upgrade to Ionic 4, but rest assured – it’s going to be way easier this time!

Because Ionic switched to Web Components with v4, most of the code is still the same for v5 as they can work on things in the background without affecting the API.

However, a few breaking changes were introduced so if you use any of them, you app might not work anymore. Let’s walk through the most important changes and how you can upgrade your existing app!
ion

Upgrade to latest Ionic 4

Before going to v5 I actually recommend to install the latest v4 version. In this version, you app will already show deprecation warnings for some elements that you should fix upfront and prepare for v5.

To do so, simply run this inside your project:

Once you are done with fixing the deprecation warnings, you can continue to v5 in which we will also fix every potential breaking element of your app.

Install Ionic 5

To update your app to the latest Ionic and Angular version, simply run this inside your project:

You don’t have to exchange any other packages or change your project structure – everything stays the same with v5!

Now that you have the latest version installed, we can get to the potential broken elements of your app.

CSS Utilities

If you didn’t already fix this using the deprecation warnings of v4, it’s time to do it now: The CSS utilities were removed!

This means, you need to change all places inside your app where you previously had something like this:

The used values are only examples, all CSS utilities were removed.

The new code now uses CSS rules like this:

This means, you need to convert the previous utilities to CSS rules pretended by ion-, and of course you can use multiple rules in combination just like any other CSS rule.

Initially I wanted to write a script for the conversion, but it’s kinda challenging since you might already have classes on elements and can’t just search/replace these values.

If you are more skilled with a scripting language, feel free to create a script and share it with the community!

Events

Another breaking change is the deprecation of the Events API.

If you are using this API to broadcast events across your app, you need to convert this to either some RxJS logic or a complete state management solution.

I will show you how to convert this quickly in a future post as well, basically you can use a Subject and emit new values to this Subject to which all other pages could subscribe instead.

Toast

A small breaking change affects your toasts, but only if you previously used showCloseButton and closeButtonText, which are now removed.

Instead of using these properties, you can now simply use the buttons array like you are used from other overlays like this:

Menu / Split Pane

If you are using a menu or a split pane with a menu, you need to change one value to make them play together correctly again.

The new syntax uses contentId instead of the main attribute, so go ahead and change your menu markup to this:

As you can see – another really simple change!

ion-nav

Most likely you never used this component anyway since the documentation was sparse and the use case rather small. Anyway, all of these were removed:

• ion-nav-push
• ion-nav-back
• ion-nav-set-root

The replacement for this is just one component called ion-nav-link, on which you can set a router-direction to cover all of the 3 component use cases above.

You can see both the old and the new usage in my Quick Win about Ionic Multi Level Menu with ion-nav.

CSS Variables

Many components got new additional CSS classes, but some were also removed or renamed. I’m not going to cover each of them, just check out the official breaking changes guide and check for the components used in your app!

Ionicons

With Ionic 5 there’s also a new version of the Ionicons package that is automatically used and installed in your app! You can read the official announcement here.

The most important change is that you can now specify different modes of the icons (outline, sharp, default) directly on an icon for iOS and Android like this:

This is not a breaking change but an addition! But some icons were also removed, so if your app is not showing some icons, you can find the full Ionicons changelog with all changed and removed icons here.

Angular 9

Not really related to Ionic 5, but while you are at it, you should also upgrade your Angular packages to Angular 9! You can read about the most important benefits of this great new Angular version on the Ionic blog as well.

Basically, you can run the update schematic inside your Ionic project like this:

Only do this after you are done with the Ionic changes, so you don’t get confused with Angular and Ionic changes inside your project!

If you want more information about what might have changed from your existing Angular version to Angular 9, you can check out this cool update helper tool!

This update also shouldn’t really break anything, but you might see some compiler errors since the compiler will now use the same checking like the final production build, which helps to eliminate issues already during development.

Previously you might have first seen these issues when you finally made a production build, so it’s actually helpful and an issue.

Additionally, the entryComponents have been removed so if you used them inside your app, that’s one of the biggest breaking changes.

Conclusion

Most of the updates target the UI of your app, and only a very small fraction of the changes is about the API of Ionic components.

Hopefully your upgrade is smooth, but the time needed of course depends on the overall size of your app.

A full document covering every possible change can also be found inside the Ionic repository.

You can find a video version of this Quick Win below.