One of the services I often perform is to spend a few hours doing a high-level code review of an Ionic codebase, and then writing up any advice or recommendations I have based on what I see. Most of the time, the request comes from people who have built an Ionic application but the performance isn’t where they want it to be.

I have written and talked quite a bit about Ionic performance in the past, and to get a general sense of my view on Ionic’s performance I would recommend reading: Ionic Framework Is Fast (But Your Code Might Not Be). The key point is that for most cases, Ionic is more than enough to build a high performance application with smooth interactions.

The “problem” is that it is relatively easy to build applications with Ionic, but a high level of skill and knowledge of the underlying technologies is required to do it well, and so it is common to see poor-performing applications built with Ionic. Ionic has a low barrier to entry, but expertise is still required to build good applications. That’s not to say that the opportunity for poor performance is exclusive to Ionic and other hybrid approaches, there are plenty of poor-performing native applications.

The reason that I am writing this article, is because I have done quite a few of these code reviews now, and there are some common issues that seem to pop up in a lot of the codebases I review.

The Problem

The key issue I think that a lot of the codebases I review face are that some of the fundamentals of a well designed Ionic application are missing, and that either creates or masks the underlying issues contributing to poor performance.

The analogy I use is that of a messy room that smells bad. The main motivation might be to get rid of the smell, but that is difficult to do whilst the room is a mess. The mess in the room might not be contributing to the smell at all, but it will make finding the source of the smell difficult. Or perhaps there is no main source of the smell, maybe all the mess in the room just smells a little bit, and all of it together is creating a big stink.

Until the codebase itself is improved from an architectural/organisational/maintainability perspective, trying to diagnose and fix performance issues is likely either going to be a difficult or futile excercise. Finding a mouldy sandwich in an otherwise clean room is much easier.

Recommendations

In the remainder of this article, I am going to list some recommendations to address the common issues that I see. These issues are not always necessarily contributors to poor performance themselves, but can end up creating that “messy room” scenario.

The points I will be listing also aren’t all-encompassing of the best practices for building Ionic applications, rather, these are specifically to address the things that I see happening most commonly.

Keep pages light

The “page” components in our applications are those that we are using to display a “view” like the home page, or a login page, or a profile page. There is a tendency for people to add all of the functionality required to make that page function into the page component itself. This can lead to bloated page components that are hard to follow and perform work that should be performed more modularly.

Instead of putting all of the code into the page itself, the page should only handle basic functionality like handling event bindings in the template (e.g. when the user clicks this button, trigger this function). Any complex “work” that needs to be done should generally be separated out into its own provider/service and then the page can interact with that. This keeps the pages light, and it will also help prevent needlessly implementing the same functionality in multiple places.

Take a login page as an example. I’m just going to make up a silly example here, but hopefully it gets the point across. You might want to add everything you need to handle the authentication process on the login page, and what ends up being creating is something that looks like this:

BAD:

public username;public password;private authToken;private apiKey;private isLoggedIn;private loggingIn;private jwt;private rememberMe;// even more class member variables go herelogin(){}checkPassword(){}storeToken(){}someOtherMethod(){}yetAnotherMethod(){}// even more methods go here

Instead of doing all of this in the login page, you should instead move all of this authentication “work” into its own provider/service/singleton. You can then just make a simple call to that service from the login page, e.g:

GOOD:

public username: string;public password: string;login(){this.authService.authenticate(this.username,this.password).subscribe((res)=>{// do something})}

Not only does this clean up the login page a great deal, but it also means that any of our pages that need to make use of any of the “authentication” functionality can do so through a single service. That means a bunch of other pages might also now be much lighter, and if there is an issue with authentication we can focus on debugging just one file rather than trying to trace what is happening through multiple different pages.

Prioritise simplicity

A lot of the time I will see code that is overly complex. Again, it might not be an issue in itself that is contributing to poor performance, but it increases the complexity of the code overall. If complex code is used all of the time where something simpler would suffice, it can lead to huge files that are hard to follow and work with.

Being able to read through some code and build a mental model of it helps a great deal when trying to understand/optimise your code. If you have methods spanning across 800 lines of code, it is going to be much harder to work with. If you just use if/else statements and for loops you can probably achieve most of what you need to do, but it is going to lead to uglier code.

For example, let’s say we are trying to remove all posts from an array that don’t have josh as the author. We could do something like this:

for(let i=0; i <this.posts.length; i++){if(this.posts[i].author !=="josh"){this.posts.splice(i,1);}}

or you could do something that looks much simpler and cleaner like this:

this.posts.filter((post)=>{return post.author ==="josh";});

This particular example doesn’t result in a massive saving in terms of lines of code, but it is much easier to understand. With the second example, it is easier to see at a glance what we are doing. The first example isn’t too bad, but if you start piling a bunch of solutions like that together things can start to get really messy - especially when we start dealing with loops within loops.

I also see similar issues in complexity in templates where there is complicated structures of grids and lots of manual positioning, where perhaps some simple CSS flexbox layout could achieve the same results in far less code. In the case of your template, this might even lead to actual performance improvements. A complicated DOM structure (e.g. lots of nodes, lots of nesting) can be a bottleneck for performance in web applications.

Making the code simpler is going to require the knowledge of how to make it simpler, and that is just something that is going to come with experience. But, if you find yourself writing code that seems complicated, see if you can start finding ways to simplify it. I find that I rarely run into situations with Ionic where I need to write code that is large/ugly/complex, even for advanced functionality.

Do it right from the beginning

It is so much easier to keep things clean in the first place than it is to tidy it up afterward. That is probably true of most things, but it is definitely true for code.

A poorly designed and messy codebase will likely just breed more poor design and code. A structured, clean, and well thought out codebase is much more likely to remain that way. Avoid the temptation to rush through just building out the “prototype” as quickly as you can, because often that prototype ends up being iterated upon and becoming your final product. At that point, the rushed and poorly designed code is so baked in that “fixing” it is usually a bigger task than just starting from scratch.

Understand how the browser works

Keeping in line with the idea of doing things right from the beginning, I think perhaps the most important things to keep in mind as you are building is the browser rendering process and the event loop.

This is something that might take a bit to understand (and it is not necessary to understand it completely), but it is so fundamental to creating well-performing web applications that it should be something you keep in mind for every bit of code that you are writing. There are ways to do the exact same thing in JavaScript, except coding it one way will result in smooth 60fps performance, and the other will slow your interface to a janky mess.

For an example of this, take a look at this video: https://www.youtube.com/watch?v=t_mo0QCbRG4.

Never use hacky solutions

Another common issue with problematic code bases is that often “hacky” solutions will be used - either because of a lack of knowledge on how to implement the solution properly or to cut corners/save time.

This creates a snowball effect that will really come back to bite you later. If you solve one thing with a hack, then any behaviour arising from that is probably going to be solved with a similar hacky solution. Eventually, you have hacks upon hacks upon hacks - you don’t even know how the codebase works anymore, and it will break for reasons that are almost impossible to debug.

This means you probably shouldn’t be manually just nudging things a few pixels around to deal with layout issues, e.g:

position: relative;right: 3px;top: 2px;

and you should be really careful whenever you think you need to use setTimeout:

// Give everything a bit of time to loadsetTimeout(()=>{// now do the thing that wasn't working},3000);

There are legitimate uses for setTimeout, but if you find yourself reaching to setTimeout to “fix” a little issue you are having, think about it five times first and then probably don’t do it. It can probably be solved with a better understanding of asynchronous code.

If you ever find yourself thinking you will just fix something quickly now with this little work around and you’ll come back to it later to implement a “real fix”, just do it correctly right away. If you don’t know how to do it correctly, then spend time researching it. Chances are that the solution you implement now will be the one that stays in the application.

Use types

If you are building Ionic applications, then you probably have TypeScript and types at your disposal. I won’t go into how types work and the benefits in this article, but for a bit of an introduction to why you might want to use them with Ionic you can take a look at this video: Using Interfaces in Ionic.

Types required just a little bit of extra effort to add to your code once you understand them, and they help a great deal in increasing code quality and preventing bugs/issues before they happen.

Use automated tests

I think that creating automated tests, and especially using a methodology like Test Driven Development (TDD), is one of the ultimate ways to create a well-designed/well-structured/stable/maintainable codebase. Not only do tests provide confidence that your code is working as expect, but using a rigorous methodology like Test Driven Development will kind of force you to write good code. It is much easier to test good code, so if your code is structured poorly you are probably going to run into a lot of difficulty creating tests until the code is designed better.

When using a TDD approach, it also forces you to slow down and consider what you are building and how you are building it. It can be difficult to learn to write tests, it is going to take longer to build applications this way, but the end result is a much more stable product that will save you more time in the long run. Even if you aren’t creating particularly good tests, even the act of trying to do it will likely result in better overall code.

For an introduction to basic testing concepts, you can take a look at this article: The Basics of Unit Testing.

Summary

As I mentioned before, this is not meant to be an exhaustive list of how you should build your Ionic applications. These are just recommendations to issues that I regularly see when reviewing Ionic codebases.

A lot of the advice I am giving relies on the developer knowing how to do things “better”, and if you don’t have that level of experience yet it is going to be hard to know what to do. Hopefully, this can serve to at least identify some things to be thinking about, and highlight what you might need to learn more about.

Although you may or may not recognise the term shared element transition, you will likely have seen this pattern applied in many applications that you have used. It is typically applied in a master/detail type of situation, where we would select a particular element to reveal more information. The basic idea is that instead of just transitioning normally to a new page, or launching a modal, the selected element “morphs” into its position on the next page.

It will look something like this:

In this tutorial, we will be walking through how to implement this in an Ionic and StencilJS application.

Animations like this are nice because they add a bit of interest and intrigue to the application, but it also serves a purpose. This particular animation helps to reinforce the concept that what is being displayed on this new page is related to the element that was selected on the previous page. Although there is a bit of smoke and mirrors going on here, it appears that we are following the element on its journey to the new page, rather than there being a distinct “switching” of pages.

How exactly you might implement this pattern in your own application will depend a lot on the context, but this tutorial will provide an example and walk through the general concepts. I have written a tutorial previously on how to create a shared element transition for an Ionic/Angular application, so although I will still cover the basic concepts here, if you would like more context I would recommend reading that tutorial as well.

The Basic Concept

There are different ways you could go about implementing this, but the approach we will be taking is actually reasonably simple. The general idea goes like this:

1. Fade in the detail page on top of the master page
2. Have the “shared” element be positioned in the same spot on the detail page as it was on the master page
3. As the detail page is fading in, animate the position of the shared element to its normal position for the detail page

Here is the exact same transition that we looked at above, but slowed down 10x:

It still might be a little difficult to tell what is going on here, so let’s break it down:

1. The user clicks one of the cards
2. The detail page starts fading in on top of the master page (nothing on the master page changes at all)
3. Information containing the position of the image on the master page is passed to the detail page
4. The header image on the detail page is initially set to appear in the same position as the image from the master page
5. Once the detail page begins displaying, the header image starts to animate into its “normal” position on the detail page

For us to implement this process in an Ionic and StencilJS application we will need to:

1. Launch a modal with a custom animation so that it fades in
2. Use componentProps to pass the image position to the detail modal
3. Using the componentDidLoad hook, set the initial position of the header image to match the position of the passed in data
4. Animate the header image back to its regular position

Let’s start stepping through how to do that now.

1. Set up the Modal Controller

First, we will need to make sure that we have the <ion-modal-controller> web component set up in our application. We will just be adding this to the app-root component. If you are not familiar with this concept already, I would recommend watching Using Ionic Controllers with Web Components. This video also covers interacting with the modal controller and modal elements, which we will be doing later on in this tutorial.

Modify src/components/app-root/app-root.tsx to include the <ion-modal-controller>:

import{ Component, h }from"@stencil/core";

@Component({
  tag:"app-root",
  styleUrl:"app-root.css"})exportclassAppRoot{render(){return(<ion-app><ion-routeruseHash={false}><ion-routeurl="/"component="app-home"/></ion-router><ion-modal-controller/><ion-nav/></ion-app>);}}

2. Create a Custom Modal Transition Animation

A key part of the shared element transition is having the detail page fade in on top of the master page. As I mentioned, we will be using a modal to overlay our detail page over the master page, but the default modal animation doesn’t use a “fade in” effect where the opacity is gradually animated from 0 to 1. Therefore, we are going to create our own custom modal animation so that we can make it do whatever we like.

We will define a custom animation in a separate file, and then pass that into the enterAnimation property for our modal. If you are not familiar with this and would like some additional context, I have another tutorial that explores this concept of creating custom animations in more depth: Create a Custom Modal Page Transition Animation in Ionic

Create a file at src/animations/fade-in.ts and add the following:

import{ Animation }from"@ionic/core";exportfunctionmyFadeInAnimation(AnimationC: Animation, baseEl: HTMLElement): Promise<Animation>{const baseAnimation =newAnimationC();const backdropAnimation =newAnimationC();
  backdropAnimation.addElement(baseEl.querySelector("ion-backdrop"));const wrapperAnimation =newAnimationC();
  wrapperAnimation.addElement(baseEl.querySelector(".modal-wrapper"));

  wrapperAnimation.beforeStyles({ opacity:1}).fromTo("translateX","0%","0%");

  backdropAnimation.fromTo("opacity",0.01,0.4);return Promise.resolve(
    baseAnimation
      .addElement(baseEl).easing("cubic-bezier(0.36,0.66,0.04,1)").duration(500).beforeAddClass("show-modal").add(backdropAnimation).add(wrapperAnimation));}

3. Create the Modal and Pass the Position Information

Now we are going to define our “master” page. We are just going to use some dummy data to create a list of cards with images. What we need to happen is that when one of these images is clicked, we will launch a modal with our custom animation, and we will also pass some additional information regarding the position of the clicked image to the modal.

Modify src/components/app-home/app-home.tsx to reflect the following:

import{ Component, State, h }from"@stencil/core";import{ myFadeInAnimation }from"../../animations/fade-in";

@Component({
  tag:"app-home",
  styleUrl:"app-home.css"})exportclassAppHome{
  @State() cards =[1,2,3,4,5];asynclaunchDetail(event){const modalCtrl = document.querySelector("ion-modal-controller");let modal =await modalCtrl.create({
      component:"app-detail",
      enterAnimation: myFadeInAnimation,
      componentProps:{
        coords:{
          x: event.target.x,
          y: event.target.y
        }}});

    modal.present();}render(){return[<ion-header><ion-toolbarcolor="light"><ion-title>Products</ion-title></ion-toolbar></ion-header>,<ion-contentclass="ion-padding">{this.cards.map(()=>(<ion-cardbuttononClick={event =>this.launchDetail(event)}><imgsrc="/assets/grateful.jpg"/></ion-card>))}</ion-content>];}}

You can see in the code above that we are importing and using our myFadeInAnimation that we created, and we also pass in the x and y position of the clicked image as componentProps. We won’t actually need to make use of the x position in this tutorial, but depending on your circumstances, you may need to.

4. Animate the Element into Position

The next step is to define our “detail” page and to set the initial position of the image to the passed in y value. We will then need to animate the image from that initial position to its “normal” position.

To achieve the animation, we will be using the Web Animations API. Ionic is actually currently working on releasing their own animations API which will closely resemble the Web Animations API, but it will be a more stable option and optimised to work with Ionic. This will work for now, but I intend to swap it out later. There is no specific way that you need to perform this animation anyway, you can do it however you like (keeping performance in mind, of course).

Modify src/components/app-detail/app-detail.tsx to reflect the following:

import{ Component, Element, h }from"@stencil/core";

@Component({
  tag:"app-detail",
  styleUrl:"app-detail.css"})exportclassAppDetail{
  @Element() el: HTMLElement;private modalElement: HTMLIonModalElement;componentDidLoad(){this.modalElement =this.el.closest("ion-modal");const y =this.modalElement.componentProps.coords.y;this.el
      .querySelector(".header-image").animate([{ transform:`translate3d(0, ${y -56}px, 0) scale3d(0.9, 0.9, 1)`},{ transform:`translate3d(0, 0, 0) scale3d(1, 1, 1)`}],{
          duration:500,
          easing:"ease-in-out"});}close(){this.modalElement.dismiss();}render(){return[<ion-header><ion-toolbarcolor="light"><ion-title>Detail</ion-title><ion-buttonsslot="end"><ion-buttononClick={()=>this.close()}><ion-iconslot="icon-only"name="close"/></ion-button></ion-buttons></ion-toolbar></ion-header>,<ion-content><imgclass="header-image"src="/assets/grateful.jpg"/><divstyle={{ padding:`20px`}}class="container"><h2>Really cool...</h2><p>
            Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum
            has been the industry's standard dummy text ever since the 1500s, when an unknown
            printer took a galley of type and scrambled it to make a type specimen book.
          </p><p>
            Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum
            has been the industry's standard dummy text ever since the 1500s, when an unknown
            printer took a galley of type and scrambled it to make a type specimen book.
          </p></div></ion-content>];}}

We get the position information from the modal inside of the componentDidLoad hook, and then we use that when defining the animation on the element with the header-image class.

We animate from these properties:

{ transform:`translate3d(0, ${y -56}px, 0) scale3d(0.9, 0.9, 1)`},

which will move the header image down into a y position that matches the passed in y value (the 56px here accounts for the header), and we also shrink it in size a bit by scaling. Then we animate it to these properties:

{ transform:`translate3d(0, 0, 0) scale3d(1, 1, 1)`}

which are just the defaults, so it will go back to its normal position at the top of the page.

Summary

Although there is a bit of set up work involved here, this animation is rather effective and it certainly makes the application look more impressive. Since we are just using the transform and scale properties, this also means that the animation should perform well.

As I mentioned, the exact implementation is going to depend on how you want your application to look and where the images need to move from and to, but this tutorial should serve well to explain the basic concepts, and you can modify it to suit your needs.

The Firebase JavaScript SDK - which we will be using in this tutorial - provides a really simple web-based method for authenticating your users in an Ionic application by using Facebook. If we are intending to launch the application as a PWA then this method will work fantastically.

However, if we are using Capacitor (or Cordova) to create native builds for the iOS/Android platforms, this web-based authentication flow becomes a little bit more awkward.

If you are using Facebook for authentication, then you are probably expecting that your users will have the native Facebook application installed on their iOS/Android device. If we make use of that native Facebook application (which the user is probably already logged into) we can provide a really smooth log-in experience, where the user will just need to click to allow access to your application.

The downside of using a web-based authentication flow is that we won’t be able to utilise the native Facebook application in the login flow, it would have to be done through the browser instead, which would likely require the user to manually enter in their username and password. This isn’t ideal, and doesn’t provide a good user experience (in fact, this is likely something that would cause users to quit the app right away).

But do not despair! In the wise words of everybody’s favourite commercial taco meme: Por qué no los dos?:

Fortunately, Capacitor (and Cordova if you prefer) will allow us to quite simply use both of these authentication methods. When our code is running on the web we will use the web-based authentication flow, and when the application is running natively we will use the native authentication flow.

Before We Get Started

Last updated for Ionic/Angular 4.7.1

This is an advanced tutorial, and I will be assuming that you already have a reasonably good understanding of how to use both Ionic and Angular, and also how to set up and configure native platforms with Capacitor. Although I won’t be explaining the more basic concepts in this tutorial, I will try to link out to additional resources where possible for those of you who might not be as familiar.

This tutorial will be specifically for Ionic/Angular, but it should be quite adaptable to other frameworks. For example, I have previously covered a similar process for an Ionic/StencilJS application that used Anonymous authentication instead of Facebook: Firebase: Anonymous Authentication. It would require a bit of tweaking, but you could implement most of the concepts we will be discussing in this tutorial in an Ionic/StencilJS application as well.

We will not be building the application from scratch in this tutorial, I will just be using a Login page and a Home page as an example which you could then integrate into however your application is set up. If you don’t already have an application to work with, just create a new blank Ionic/Angular application:

ionic start ionic-facebook-login blank --type=angular

create a Login page:

ionic g page Login

and set up your routes in src/app/app-routing.module.ts as follows:

import{ NgModule }from"@angular/core";import{ PreloadAllModules, RouterModule, Routes }from"@angular/router";const routes: Routes =[{ path:"", redirectTo:"login", pathMatch:"full"},{ path:"home", loadChildren:()=>import("./home/home.module").then(m => m.HomePageModule)},{ path:"login", loadChildren:"./login/login.module#LoginPageModule"}];

@NgModule({
  imports:[RouterModule.forRoot(routes,{ preloadingStrategy: PreloadAllModules })],
  exports:[RouterModule]})exportclassAppRoutingModule{}

The general idea is that we want the Login page to be the default page, and then we will go through our authentication process before proceeding to the Home page. On future visits to the application, this process should happen automatically (unless the user manually logs out).

1. Set up Facebook

First, we are going to set up everything that is required to interact with Facebook. This will involve quite a few different steps including:

• Creating an application through the Facebook developer portal
• Installing plugins/packages in our application
• Creating a key hash (if you are building for Android)
• Configuring for the native platforms

Each of these steps individually are quite straight-forward, but there is a bit to get through.

1.1 Configure the App with Facebook

First, we will register our application through the Facebook developer portal. To do that, follow these steps:

1. Go to developers.facebook.com and create an account if necessary
2. Go to My Apps and click Create App
3. Add a Display Name and click Create App ID
4. Under Add a Product click Set Up on Facebook Login
5. Select Settings from the left side menu (we don’t want to use the “Quickstart” we are presented with initially)
6. Select Basic
7. From here, you will be able to see your App ID and App Secret - make a note of both of these for later
8. Scroll to the bottom and click + Add Platform
9. Select iOS (if you are building for iOS) and add the Bundle ID of your application (e.g. com.yourcompany.yourapp)
10. Select + Add Platform again and then select Android (if you are building for Android) and add your Bundle ID to the Google Play Package Name
11. Click Save Changes

If you are building for Android you will also need to create a key hash of your keystore file that will be used to sign your Android application. You will need to provide a key hash for the keystore file you use for the production version of your application, but throughout development, you can just provide a key hash of the default debug.keystore file used by Android Studio.

If you are using a Mac, you can use the following command:

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64

or if you are using Windows you can use the following command (this will require OpenSSL):

keytool -exportcert -alias androiddebugkey -keystore %HOMEPATH%\.android\debug.keystore | openssl sha1 -binary | openssl
base64

You will need to enter the password: android. Once you do this, your key hash will be displayed on the screen and you can add it to the Key Hashes field in the Facebook devleoper portal. Remember that you will need to update this key hash later (or add an additional one) to reflect the keystore file that is used to sign the production version of your application.

NOTE: If you do not already have a JDK installed you may be asked to do so when performing this step. Typically, this isn’t required because Android Studio comes bundled with its own JDK. However, attempting to use this command from your terminal to generate the key hash will require the JDK to be installed separately from Android Studio. If you are on a Mac, you can get around this requirement by using the keytool command in the context of Android Studio like this:

/Applications/Android\ Studio.app/Contents/jre/jdk/Contents/Home/bin/keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64

1.2 Install the Required Dependencies

In order to interact with the Facebook API, we will be installing the cordova-plugin-facebook4 plugin, as well as the matching Ionic Native package for using this plugin. You can install both of these by running the following commands:

npm install cordova-plugin-facebook4 --save

npm install --save @ionic-native/facebook

Since we are using Ionic Native, we will also need to add this plugin into the app.module.ts file as a provider.

Modify src/app/app.module.ts to include the Facebook plugin:

import{ NgModule }from"@angular/core";import{ BrowserModule }from"@angular/platform-browser";import{ RouteReuseStrategy }from"@angular/router";import{ IonicModule, IonicRouteStrategy }from"@ionic/angular";import{ AppComponent }from"./app.component";import{ AppRoutingModule }from"./app-routing.module";import{ Facebook }from"@ionic-native/facebook/ngx";

@NgModule({
  declarations:[AppComponent],
  entryComponents:[],
  imports:[BrowserModule, IonicModule.forRoot(), AppRoutingModule],
  providers:[
    Facebook,{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
  bootstrap:[AppComponent]})exportclassAppModule{}

1.3 Configure the Native Platforms

There is just one more step we need to complete now. In order for the Cordova plugin to work, we need to configure our applications APP_ID and APP_NAME with the native iOS/Android platforms. We can not use “install variables” when using Capacitor, so we will just need to add these values directly to the native projects.

NOTE: This section assumes that you already have Capacitor installed and have added the iOS/Android platforms. If you need more information on installing Capacitor and adding native platforms, you can read more here: Using Capacitor with Ionic.

Run the following command to open your project in Android Studio:

ionic cap open android

Once the project is open, you will need to open the following file:

android > app > src > main > res > values > strings.xml

Inside of this file, you will need to add the following entries inside of the <resources> tag:

<stringname="fb_app_id">YOUR APP ID</string><stringname="fb_app_name">YOUR APP NAME</string>

Make sure to replace YOUR APP ID with your Facebook App ID and YOUR APP NAME with your Facebook App Name. Now we need to do something similar for iOS. Open the iOS project with:

ionic cap open ios

Once the project is open, you should:

1. Click App from the left menu (above Pods, select it don’t expand it)
2. In the right panel, click the Info tab
3. Under Custom iOS Target Properties hover over any of the existing Keys and click the little + icon to add a new key
4. Create a new entry for FacebookDisplayName, set it to String, and add your Facebook App Name
5. Crete a new entry for FacebookAppID, set it to String, and add your Facebook App ID as the value
6. Crete a new entry for FacebookAutoLogAppEventsEnabled, set it to Boolean, and set the value to NO
7. Crete a new entry for FacebookAdvertiserIDCollectionEnabled, set it to Boolean, and set the value to NO
8. You will need to add an array of values under the LSApplicationQueriesSchemes key, add the key and set it to Array, and then add the following items under that array (by first clicking to expand the key - the arrow should point down - and then right click > Add Row):

The items in the image above are:

• Item 0 - String - fbshareextension
• Item 1 - String - fb-messenger-api
• Item 2 - String - fbapi
• Item 3 - String - fbauth2

You will also need to add a new URL Scheme that reflects your Facebook App ID prefixed with fb, like this:

Just scroll down to URL Types and click the + button to add a new URL scheme. You will need to put the fbxxxxx value in the URL Schemes field. If you do not do this, you will get an error complaining about not having the URL scheme registered:

Terminating app due to uncaught exception 'InvalidOperationException', reason: 'fb123456789 is not registered as a URL scheme.

You will also need to update your capacitor.config.json file to include the cordovaLinkerFlags property under ios:

{"appId":"io.ionic.starter","appName":"ionic-angular-firebase-facebook","bundledWebRuntime":false,"npmClient":"npm","webDir":"www","ios":{"cordovaLinkerFlags":["-ObjC"]}}

2. Set up Firebase

We will also need to set up a few things in order to use Firebase in our application, this is quite a bit simpler than the Facebook steps. First, we need to install the firebase package:

Run the following command to install Firebase:

npm install firebase --save

If you would like a little more context/explanation for getting Firebase set up and installed in your application, I would recommend watching the video I linked to earlier: Firebase: Anonymous Authentication. This walks through setting up everything required on screen (except for a StencilJS application). I will just outline the basic steps you need to follow below.

1. Go to console.firebase.google.com and click Add Project (assuming you have an account)
2. Once you have created the project and are taken to the Dashboard, click the web icon </> above where it says Add an app to get started
3. After this step, you will be given your configuration code. We will not be using that code as is in our application, but we will need the details in the config object. Make note of this for later (or you can just come back to the dashboard again to get the configuration code).

You will also need to enable Facebook Authentication inside of Firebase, to do this follow these steps:

1. Click on Authentication from the menu on the left side of the screen
2. Enable Facebook as a Sign-in method and add your App ID and App secret from the Facebook application you created in the previous step
3. Copy the OAuth redirect URI and add it to Products > Facebook Login > Settings under Valid OAuth Redirect URIs in your application in the Facebook developer portal
4. Click Save

NOTE: Keep in mind that there is also a package available called @angular/fire that you can use to help integrate an Angular application with the various features Firebase offers. Our requirements for this example are quite simple, but depending on what you are trying to do, you might consider using this package.

3. Create the Auth Service

With all of the configuration out of the way, we can finally get to implementing the functionlaity in our application. We are going to create an Auth service that will handle everything for us in an easy to use way. The basic idea is that we will simply call login() or logout() through the service, and it will handle everything for us and figure out the best authentication flow (web or native) for the platform the application is running on.

To create this Auth service, you can run the following command (or you might prefer to add this functionality to one of your own services):

ionic g service services/Auth

We are going to implement the entire code for this at once, and then talk through it.

Modify src/services/auth.service.ts to reflect the following:

import{ Injectable, NgZone }from"@angular/core";import{ Platform }from"@ionic/angular";import{ Facebook }from"@ionic-native/facebook/ngx";import{ BehaviorSubject }from"rxjs";import firebase from"@firebase/app";import"@firebase/auth";

@Injectable({
  providedIn:"root"})exportclassAuthService{public loggedIn: BehaviorSubject<boolean>=newBehaviorSubject<boolean>(false);constructor(private platform: Platform,private zone: NgZone,private facebook: Facebook){}init():void{// Your web app's Firebase configurationconst firebaseConfig ={
      apiKey:"YOUR-API-KEY",
      authDomain:"YOUR-DOMAIN.firebaseapp.com",
      databaseURL:"YOUR-URL",
      projectId:"YOUR-PROJECT-ID",
      storageBucket:"",
      messagingSenderId:"********",
      appId:"*******"};// Initialize Firebase
    firebase.initializeApp(firebaseConfig);// Emit logged in status whenever auth state changes
    firebase.auth().onAuthStateChanged(firebaseUser =>{this.zone.run(()=>{
        firebaseUser ?this.loggedIn.next(true):this.loggedIn.next(false);});});}login():void{if(this.platform.is("capacitor")){this.nativeFacebookAuth();}else{this.browserFacebookAuth();}}asynclogout(): Promise<void>{if(this.platform.is("capacitor")){try{awaitthis.facebook.logout();// Unauth with Facebookawait firebase.auth().signOut();// Unauth with Firebase}catch(err){
        console.log(err);}}else{try{await firebase.auth().signOut();}catch(err){
        console.log(err);}}}asyncnativeFacebookAuth(): Promise<void>{try{const response =awaitthis.facebook.login(["public_profile","email"]);

      console.log(response);if(response.authResponse){// User is signed-in Facebook.const unsubscribe = firebase.auth().onAuthStateChanged(firebaseUser =>{unsubscribe();// Check if we are already signed-in Firebase with the correct user.if(!this.isUserEqual(response.authResponse, firebaseUser)){// Build Firebase credential with the Facebook auth token.const credential = firebase.auth.FacebookAuthProvider.credential(
              response.authResponse.accessToken
            );// Sign in with the credential from the Facebook user.
            firebase
              .auth().signInWithCredential(credential).catch(error =>{
                console.log(error);});}else{// User is already signed-in Firebase with the correct user.
            console.log("already signed in");}});}else{// User is signed-out of Facebook.
        firebase.auth().signOut();}}catch(err){
      console.log(err);}}asyncbrowserFacebookAuth(): Promise<void>{const provider =newfirebase.auth.FacebookAuthProvider();try{const result =await firebase.auth().signInWithPopup(provider);
      console.log(result);}catch(err){
      console.log(err);}}isUserEqual(facebookAuthResponse, firebaseUser): boolean {if(firebaseUser){const providerData = firebaseUser.providerData;

      providerData.forEach(data =>{if(
          data.providerId === firebase.auth.FacebookAuthProvider.PROVIDER_ID&&
          data.uid === facebookAuthResponse.userID
        ){// We don't need to re-auth the Firebase connection.returntrue;}});}returnfalse;}}

First of all, notice that we are using a BehaviorSubject:

public loggedIn: BehaviorSubject<boolean>=newBehaviorSubject<boolean>(false);

We are providing this loggedIn observable that we will be able to subscribe to elsewhere, and it will emit data whenever the user logs in or out. We are going to utlise this to trigger our page navigations when necessary. You might wish to implement this in a different way for your own purposes.

Next, we have our init() function that handles configuring Firebase - you will need to make sure to replace the values here with your own config that was provided to you in the Firebase dashboard earlier. As well as configuring Firebase, we also do this:

firebase.auth().onAuthStateChanged(firebaseUser =>{this.zone.run(()=>{
    firebaseUser ?this.loggedIn.next(true):this.loggedIn.next(false);});});

We set up a listener for onAuthStateChanged which will trigger every time the user logs in or out. When this happens, we want to trigger that loggedIn observable that we created. If there is a firebaseUser it means the user is logged in and so we trigger the observable with true, otherwise we trigger it with false.

Notice that we run this code inside of the run method of NgZone. Since these auth state changes are originating from the Firebase SDK, it is occurring outside of Angular’s “zone”, and so we might run into trouble with Angular’s change detection not triggering as a result of this. To solve this, we just force the code to run inside of Angular’s zone by using NgZone.

Our login() function is quite simple, but it is responsible for the “cleverness” of our service. It just detects whether the application is running natively (i.e. on the capacitor platform) or if it is running through the web. We trigger two different authentication functions depending on the platform.

In both cases, we are just using the authentication code that is provided by Firebase (with some slight modifications). In the case of our “native” authentication, we are manually retrieving the authResponse from Facebook by using the Facebook plugin that we installed - this will allow us to grab the required information for Firebase from the native Facebook application installed on the device. In the case of a “browser” environment, we just run the regular Firebase signInWithPopup method.

We have also defined a logout method that will sign the user out of both Facebook and Firebase. If the application is not running natively, we skip the native Facebook log out.

Before we move on, there is one more thing we need to do, and that is to trigger the init method of our Auth service at some point. A good place to do this is in the root component.

Call init inside of src/app/app.component.ts:

import{ Component }from"@angular/core";import{ Platform }from"@ionic/angular";import{ SplashScreen }from"@ionic-native/splash-screen/ngx";import{ StatusBar }from"@ionic-native/status-bar/ngx";import{ AuthService }from"./services/auth.service";

@Component({
  selector:"app-root",
  templateUrl:"app.component.html",
  styleUrls:["app.component.scss"]})exportclassAppComponent{constructor(private platform: Platform,private splashScreen: SplashScreen,private statusBar: StatusBar,private authService: AuthService
  ){this.initializeApp();}initializeApp(){this.authService.init();this.platform.ready().then(()=>{this.statusBar.styleDefault();this.splashScreen.hide();});}}

4. Use the Auth Service

Finally, we just need to make use of our Auth service. To do that, you might implement some logic on your Login page that looks like this:

import{ Component, OnInit }from"@angular/core";import{ NavController, LoadingController }from"@ionic/angular";import{ AuthService }from"../services/auth.service";

@Component({
  selector:"app-login",
  templateUrl:"./login.page.html",
  styleUrls:["./login.page.scss"]})exportclassLoginPageimplementsOnInit{private loading;constructor(public authService: AuthService,private navCtrl: NavController,private loadingCtrl: LoadingController
  ){}asyncngOnInit(){awaitthis.showLoading();this.authService.loggedIn.subscribe(status =>{this.loading.dismiss();if(status){this.navCtrl.navigateForward("/home");}});}asynclogin(){awaitthis.showLoading();this.authService.login();}asyncshowLoading(){this.loading =awaitthis.loadingCtrl.create({
      message:"Authenticating..."});this.loading.present();}}

The key part here is that we subscribe to that loggedIn observable, and then trigger the navigation if we receive a true value from that. All we need to do is call the login method at some point to kick off the process (e.g. when the user clicks the login button). We have also added in a loading overlay here so that something is displayed whilst the authentication with Facebook is happening.

We can also do something like the following on the Home page to log the user out:

import{ Component, OnInit }from"@angular/core";import{ NavController }from"@ionic/angular";import{ AuthService }from"../services/auth.service";

@Component({
  selector:"app-home",
  templateUrl:"home.page.html",
  styleUrls:["home.page.scss"]})exportclassHomePageimplementsOnInit{constructor(public authService: AuthService,private navCtrl: NavController){}ngOnInit(){this.authService.loggedIn.subscribe(status =>{if(!status){this.navCtrl.navigateBack("/login");}});}}

Summary

The result of the work we have done above is a seamless login experience with Facebook, regardless of whether the application is running as a PWA or natively on iOS or Android. There is quite a lot of set up work involved to get the native Facebook authentication working, but it is well worth it for the improved experience that it provides.

We have covered a lot in this tutorial, and I didn’t want to bloat it with even more stuff. However, it would also be a good idea to combine this functionality with an “auth guard” to “protect” specific routes from being accessed by users that are not authenticated. I have another tutorial available on doing that which you can check out here: Prevent Access to Pages in Ionic with Angular Route Guards.

When building applications with Ionic, we will often need to fetch some data over the network - whether that is locally to pull in data from a JSON file, or through the Internet to load data supplied by some API.

If you’ve been around for a while you might recall using an XMLHttpRequest() to perform HTTP requests with JavaScript - this wasn’t/isn’t a particularly nice way to perform requests, and many people would use additional libraries to help simplify the process of sending HTTP requests.

Browser APIs have come a long way over the years, and now we have the Fetch API that is built in to modern browsers by default available to us. This API makes it much simpler to execute HTTP requests without the use of an external library. It performs a similar role to the standard XMLHttpRequest, but it uses Promises and is much simpler to use. A simple request using the Fetch API might look something like this:

let response =awaitfetch("https://someapi.com/data");let json =await response.json();

We can run the code above in our Ionic applications with no need to install any 3rd party libraries. In this tutorial, we are going to walk through the basics of using the Fetch API.

This tutorial has an intended audience of Ionic/StencilJS developers, since using the Fetch API could be considered the default method for running HTTP requests in that context. If you are using Ionic/Angular, for example, you would be more likely to use Angular’s HttpClient. However, the Fetch API is just a generic browser API that can be used anywhere.

NOTE: If you are interested in using Redux in your Ionic/StencilJS applications, I already have a much more advanced tutorial for loading data with the Fetch API and Redux here: State Management with Redux in Ionic & StencilJS: Loading Data.

GET Requests

We are going to discuss some basic examples of using the Fetch API. Keep in mind that we are just going to display the basic request here, but error handling is also an important topic that we will cover in the last section of this tutorial.

To execute a GET request with the Fetch API, we would do the following:

let response =awaitfetch("https://someapi.com/data");let json =await response.json();

We supply the URL that we want to fetch the data from to the fetch method. This will return a Promise with the result, so we await it (if you prefer, you could also use the standard Promise syntax with .then()). Once the Promise resolves, we can then access the data returned through the json() method.

POST Requests

Running GET requests are usually a bit easier than POST requests, because we typically need to send a bit of extra information with a POST request. We need to send the data itself, as well as any additional headers that might need to be set.

This example is a little bit more complex, but still quite manageable:

let data ={
    comment:'hello',
    author:'josh'};let response =awaitfetch("https://someapi.com/comments",{
    method:'POST',
    body:JSON.stringify(data),
    headers:{'Content-Type':'application/json'}});let json =await response.json();

We have defined some data that we want to send along to someapi.com. Now instead of just supplying the URL to fetch, we supply an Object as a second parameter. This object contains all of the extra information we need.

We use this object to set the method to POST, we add the data we want to send to body as a JSON string, and then we set the appropriate Content-Type header (which is usually going to be application/json). Aside from that, the rest is the same. We just await the fetch and the json() method.

Handling Errors

One perhaps awkward aspect of the Fetch API is that it will not cause a Promise to reject in the case of an HTTP error. This means that even if there is some kind of server error like a 500 - Internal Server Error the request will still be considered to have executed successfully. A request was made to the server, and a response was received back from the server - technically, you could consider that a “success” even if the response was an error.

That means that if we were simply to wrap our code in a try/catch block (as we might usually do to handle errors), it won’t trigger the catch block under all circumstances:

try{let response =awaitfetch("https://someapi.com/data");let json =await response.json();}catch(err){
  console.log(err);}

What will happen is that we will receive the response back successfully through the resolved Promise, but the ok status will be false if a server error occurred. In the context of our application, we would probably consider a server error to be undesirable behaviour and we would want to trigger some kind of error handling. To handle this situation, we will just need to add a little more logic to our request:

try{let response =awaitfetch("https://someapi.com/data");if(!response.ok){thrownewError(response.statusText);}let json =await response.json();}catch(err){
    console.log(err);}

Now we check the response for the ok status, and if it is not true we throw an error. Since this is inside of the try block, if we throw an error it will cause it to fail and trigger the catch, which will result in the error being logged out in this case.

Rather than manually writing this code for every request, you might prefer to set up a little helper function to help handle errors, e.g:

try{let response =awaitfetch("https://someapi.com/data");handleErrors(response);let json =await response.json();}catch(err){
    console.log(err);}

In this case, we can just pass the response to a handleErrors method that we have defined, and then throw an error in that method if necessary.

Summary

There are many approaches we can take to performing HTTP requests in our Ionic applications, and using an additional library to handle those requests is absolutely fine. In the case of Ionic/Angular, it even makes more sense to use the default HttpClient that is included since. However, it is nice that we now have a default browser API that is simple enough to use out of the box to perform HTTP requests without requiring any additional libraries.

If you are building Ionic/StencilJS applications, then you might also be interested in combining this concept of using the Fetch API with a service to handle performing those requests for you. If you are interested in a more advanced data loading implementation with Redux, remember to check out State Management with Redux in Ionic & StencilJS: Loading Data.

One of the key ideas behind the Capacitor project which was created by the Ionic team, is to provide access to browser/native features through a single API no matter what platform the application is running on. This philosophy makes the one codebase/multiple platforms approach to building applications much more feasible.

Geolocation is a good example of where this can simplify things a great deal for us. How we implement Geolocation may depend on what platform we are running on, e.g: iOS, Android, or the web. However, we don’t need to write a bunch of conditions into our application and run different code based on the platform (or perhaps build slightly different versions of our application for each platform), we can just make a single call to Capacitor’s Geolocation API:

Geolocation.getCurrentPosition();

It isn’t always so simple. Naturally, the web and native applications have accesss to a different set of functionality, and not all native functionality is going to be able to run on the web. If a particular Capacitor API does not have a web implementation, then you won’t be able to use it.

If you try to use the Camera API, for example, you are going to find that it won’t work:

Uncaught (in promise) TypeError: cameraModal.componentOnReady is not a function
    at CameraPluginWeb.<anonymous> (app-home.entry.js?s-hmr=225807175348:648)

There is good news though, we can actually get the Camera API to work on the web as well - as long as the user has some kind of web camera we will be able to take a photo using that camera.

The Ionic team have another library called PWA Elements. This library provides web-based implementations for some of Capacitor’s APIs. Where it is possible for the functionality to be implemented through the web, the PWA Elements library can provide the interface elements required to provide a sleek experience on the web as well. The Camera API is one example of this. If we install the @ionic/pwa-elements package, we can launch a camera modal that will allow the user to take a photo on the web.

In this tutorial, we will be walking through exactly how to do this. We will be using an Ionic/StencilJS application as an example, but the same general concept will apply no matter what kind of framework/application you have Capacitor set up in.

Before We Get Started

This tutorial will assume that you already have Capacitor installed in your project, and that you are already comfortable with creating applications in the framework of your choice.

If you are not familiar with Capacitor you can find more information about getting started in the documentation.

1. Installing PWA Elements

We will first need to install the PWA Elements package. To do that, just run the following command in your project:

npm install @ionic/pwa-elements

You will also need to set up pwa-elements in your code, but this will vary depending on what framework/approach you are using. I am using Ionic/StencilJS for this example, and all you will need to do to set up PWA Elements in this environment is to add the following import to the src/global/app.ts file:

import"@ionic/pwa-elements";

If you are using Angular or React or some other framework (or none at all), the steps for loading PWA Elements can be found here: Installation Instructions for PWA Elements.

2. Trigger the Camera API

Next, we will need to implement the code for capturing a photo. The Capacitor Camera API makes this simple enough, we will just need to implement a function like the following:

import{ Component, h }from"@stencil/core";import{ Plugins, CameraResultType }from"@capacitor/core";const{ Camera }= Plugins;

@Component({
  tag:"app-home",
  styleUrl:"app-home.css"})exportclassAppHome{asynctakePicture(){const image =await Camera.getPhoto({
      resultType: CameraResultType.Uri
    });
    console.log(image);}render(){return[<ion-header><ion-toolbarcolor="primary"><ion-title>Home</ion-title></ion-toolbar></ion-header>,<ion-contentclass="ion-padding"><ion-buttononClick={()=>this.takePicture()}>Take photo</ion-button></ion-content>];}}

Again, this will look a little different depending on the framework you are using, but the same basic concept is the same. Once you serve your application in the browser and trigger that takePicture method the Ionic/Capacitor Camera API will ask for permission to use the camera. Once you grant permission it will display a camera preview overlay that looks like this:

This will stream video into the application from the computers web camera, and you will be able to see this live feed as you move around. When you click the circle button a photo will be captured and the photo will be resolved as the result of the getPhoto call to the Camera API based on the resultType that is being used.

In the example above, we are using Uri which will store the resulting photo as a BLOB locally. If you were to go to this address in your browser, for example (using your own result from the getPhoto method and in an Ionic/StencilJS application):

blob:http://localhost:3333/7888d45e-4e65-4d19-a157-e06dc5d147ff

You would be able to view the photo. You could also instead set the resultType to Base64 or DataUrl to return the photo data in those formats instead, e.g:

{dataUrl: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD…8Nj80tM5paCR1FNzRmgBwpaaKWmAuaUGm0oNMQpNFJRTA/9k=", format: "jpeg"}

If you are attempting to create a solution that works on both the web and native iOS/Android, you may need to take a different approach to what you actually do with the resulting photo based on the platform. For example, on iOS/Android you might want to implement a solution like the one discussed in this tutorial: Using the Capacitor Filesystem API to Store Photos. That tutorial describes a process for permanently storing photos natively, but you can’t use that same approach for the web version, so you would need to implement slightly different solutions depending on what it is exactly that you want to do - you might want to try some sort of local storage solution, or perhaps it is more appropriate for you to store the images on some kind of server.

Summary

The PWA Elements package provides a really sleek way to implement the Camera API in a web environment, whilst also making it possible to utilise the standard native camera functionality when the application is running in that environment. This goes a long way to helping us get to that dream of writing code that just works on all platforms, but for now at least, there are still going to at least be some differences that need to be catered for which might result in a few extra if/else conditions if we want to run on all platforms.

You know what’s way cooler than horizontal progress bars? Circle progress bars! Well, for some contexts at least. Circles are a little bit more difficult to work with in CSS that squares/rectangles where we can just define a simple width/height for the shape, but with some effort we can create something that looks like this:

There are different ways to go about implementing a circle component like this, but I am going to walk through a rather simple method for achieving the effect with conic gradients. The basic idea is that we can use the conic-gradient that CSS provides to create a radial gradient that looks something like this:

If we then overlay another circle shape ontop of the gradient, we can achieve the circular progress bar effect quite easily:

The best part of this approach is how lightweight the solution is, with the key aspect being this CSS property:

background:conic-gradient(green 34%, 0, grey 66%);

This will create a gradient similar to the example that you can see above with a circular bar 34% of the way around the full circle. To make this into a more dynamic component, we will need to implement a way to configure both the colour values and the percentages for that CSS property.

NOTE: The conic-gradient value is not currently fully supported by all browsers. It is supported on Chrome/Safari (both desktop and iOS/Android), but Internet Explorer/Firefox and others do not support conic-gradient yet. If you do require support for these browsers, and want to use this component, there is a polyfill available.

Before We Get Started

We are going to create this component as a standalone web component using StencilJS. Although we will be focusing specifically on StencilJS, you could still follow this tutorial to apply the same concept elsewhere. For example, you could build this directly into an Ionic/StencilJS application (rather than creating a standalone component), or as an Angular component, or use the same concepts in your React application. We are just working with standard web stuff here.

This tutorial was written with Ionic developers in mind, but there also isn’t anything specific to Ionic or mobile applications here. If you are following along with StencilJS, I will assume that you already have a basic understanding of creating custom web components with StencilJS

1. Create the Component

We will be creating a component called my-circle-progress but you can rename this to whatever you prefer. Just make sure that you create a my-circle-progress.css and my-circle-progress.tsx file inside of the components folder in your StencilJS project.

The basic outline of the component will look like this:

import{ Component, Prop, h }from"@stencil/core";

@Component({
  tag:"my-circle-progress",
  styleUrl:"my-circle-progress.css",
  shadow:true})exportclassMyCircleProgress{
  @Prop() progressAmount: string ="0";
  @Prop() progressColor: string ="#2ecc71";render(){return(<div><div><span>
            75%
          </span></div></div>);}}

We will use two props that can be used to pass in values to this component. The progressAmount will be used to determine how much of the circle should be filled (and it will default to 0 if no value is supplied), and the progressColor will be used to determine the colour of the progress wheel (which defaults to a nice green colour).

Our template has a <div> for the element that will hold our conic-gradient background, and another <div> for the overlay that will sit on top of the gradient and contain the percentage number. We are going to define the styles directly on the elements - the CSS is quite short and it makes the tutorial easier to follow - but if you prefer, you could add classes to these divs and add your styles to the my-circle-progress.css file instead.

2. Implement the Conic Gradient

First, let’s take a look at how we can create the gradient required for our circle.

Modify the template to reflect the following:

render(){return(<divstyle={{
          width:`100%`,
          height:`100%`,
          display:`flex`,
          alignItems:`center`,
          justifyContent:`center`,
          background:`conic-gradient(${this.progressColor}${this.progressAmount}%, 0, #ecf0f1 ${(100-parseInt(this.progressAmount)).toString()}%)`,
          borderRadius:`50%`}}><div><span>{this.progressAmount}</span></div></div>);}

Creating a circle in CSS is simple enough - we just use a border-radius of 50%. The tricky part here is setting up the gradient. As we discussed earlier, we can add a conic-gradient like this:

background:conic-gradient(green 34%, 0, grey 66%);

Which would fill our circle with 34% green and 66% grey in a clock-wise manner. We need to make this dynamic. Ideally, we want to be able to pass in a number (e.g. 67) and then have the circle fill up with our main colour 67% of the way. All we need to do to achieve this is supply the desired number as the first percent value, and then 100 - (the number) as the second percentage value. We do this by passing in our progressAmount prop that we defined on the component.

We also pass in the progressColor prop to dynamically set the colour. We use a default grey for the background of #ecf0f1 but you could make this dynamic too if you wanted to (by using another prop, setting up a CSS variable, or turning off Shadow DOM on the component).

We have also added some other styles aside from the borderRadius and background. We want the circle to fill up all the available space, and we will also need the overlay (the <div> inside of the one we are currently working on) to be centered both vertically and horizontally - so, we use a flex layout with alignItems and justifyContent to achieve this.

At this point, our circles should look like a pie chart:

3. Add the Overlay

To make our circles look less like a pie chart and more like a progress wheel, we need to add another circle overlay on top. This will give the appearance of cutting out the middle section of the circle, and will create the effect of a bar rotating around a circle.

Modify the template to reflect the following:

render(){return(<divstyle={{
          width:`100%`,
          height:`100%`,
          display:`flex`,
          alignItems:`center`,
          justifyContent:`center`,
          background:`conic-gradient(${this.progressColor}${this.progressAmount}%, 0, #ecf0f1 ${(100-parseInt(this.progressAmount)).toString()}%)`,
          borderRadius:`50%`}}><divstyle={{
            display:`flex`,
            alignItems:`center`,
            justifyContent:`center`,
            backgroundColor:`#fff`,
            height:`80%`,
            width:`80%`,
            borderRadius:`50%`,
            boxShadow:`0px 0px 7px 0px rgba(0, 0, 0, 0.1)`}}><spanstyle={{
              fontFamily:`"Helvetica Neue", Helvetica, Arial, Verdana, sans-serif`,
              fontSize:`2em`,
              fontWeight:`lighter`}}>{this.progressAmount}</span></div></div>);}

This overlay is a more simple circle. To make sure that we can still see the gradient behind the circle, we give this circle a width/height of 80% - this will leave the edges of the gradient behind it visible. We also add a box-shadow but this is not required, it just creates a nice little effect to give the component some depth.

Once again, we use a flex layout because we will also need to center the number that will be displayed on top of the circle, and we also add a bit of styling to our text.

4. Use the Component

The component is completed now! If you have been building this with StencilJS you can add the component to your index.html file to see a preview of what it looks like:

<body><divstyle="display: flex;align-items: center;flex-direction: column"><divstyle="width: 170px;height: 170px;margin: 20px;"><my-circle-progressprogress-color="#e74c3c"progress-amount="15"></my-circle-progress></div><divstyle="width: 100px;height: 100px;margin: 20px;"><my-circle-progressprogress-color="#f1c40f"progress-amount="54"></my-circle-progress></div><divstyle="width: 220px;height: 220px;margin: 20px;"><my-circle-progressprogress-color="#2ecc71"progress-amount="100"></my-circle-progress></div></div></body>

You can have a play around and use whatever colours/progress amounts you like.

Summary

We now have a resuable component that can be easily used anywhere - if you built this with StencilJS you will also be able to use it anywhere that supports web components. You will just need to publish the component in some manner.

If you enjoyed this tutorial, let me know in the comments or on Twitter. If there is interest in this component I’d like to take it a bit further, perhaps by extending it to function as an animated timer or event an input mechanism.

Animations are one of those little extra touches in an application that can transform an average looking application into something truly impressive. When done well, we can create animations that perform well, look great, and improve the user experience of our application.

There is a lot of talk around the performance of web-based or hybrid mobile applications, but it is often irrelevant as web tech is capable of smoothly running most (but not all) types of mobile applications. However, animations are one of those legitimate areas of concern for performance when using a web-based approach. Animations, in some cases, will need to make use of the extra computing power that is available to native applications that aren’t making use of the browser to render the user interface.

There will be more limitations for animations when using a web-based approach, but that does not mean that we can not do animations effectively with Ionic. It is just important that we understand a few concepts and how best to approach designing the animations - simple changes in the approach to an animation can transform it from being extremely laggy/janky to smooth and performant.

The more complex the animations become, the more they will need to be optimised, and some types of animations might not be feasible for Ionic applications. A big factor to consider is the types of devices you intend for your application to run on, as older devices may have a harder time running animations that may perform smoothly on more modern devices.

However, we can actually achieve quite a lot in terms of animation with very little impact on performance - probably a lot more than some people might think. As an example, take a look at this custom page transition animation that I created in one of my recent UI Challenge videos:

Episode #2 of my UI Challenge series is up! This time we live code an expanding button screen transition animation for @ionicframework and cover:

✅ Animating with Transforms
✅ Page Transition Animations
✅ CSS Variables
✅ Sneaky Tricks

Full video 👉 https://t.co/Vk7hva794fpic.twitter.com/IrtT2GPA1t

— Josh Morony (@joshuamorony) November 19, 2019

It looks quite cool and complex - it appears as if the button is expanding and morphing into the new page that is being displayed. Aside from looking cool, this animation also achieves something in terms of user experience. Rather than just transitioning directly to a new page, it makes the connection between the cart button and the cart button much more obvious, as one transitions smoothly into the other.

Despite how complex the animation may look, it actually uses very simple techniques that are easy for the browser to perform. I’ll let you watch the video if you are interested in the full implementation but the basic idea is using a CSS transition to animate the transform property on the button to:

transform:scale3d(35,35,1)

which makes it big enough (35 times its original size in this case) to fill the whole screen, and then using a custom page transition animation that Ionic supports to fade in a modal rather than using the default transition animation.

The combination of these two simple techniques leads to an effect that is impressive, easy to implement, and also cheap in terms of performance. That is what the rest of this article is going to be about: how to identify and use simple techniques that can lead to impressive and efficient animations. The point of this article is not to cover all of the impressive things you could do with animations in Ionic, but rather how you can get a lot of value from just understanding a few reasonably simple concepts and techniques.

1. Understand browser rendering

Aside from wanting our animations to be cool/relevant/interesting the key goal is to get them to feel fluid and smooth. The most impressive animation is going to detract from the application if it feels jumpy or janky or laggy.

The basic idea behind creating an experience that feels smooth is that our application continues to render at around, at least, 60fps (frames per second) and is able to deliver “instantaneous” feedback to the user - if the user interacts with the application (e.g. by swiping or clicking a button) it should respond with some kind of feedback within about 80ms which will make the interaction feel instant to the user.

This means that we need to make our applications efficient enough that the browser can render visual changes to the screen at least 60 times per second. This will mean the user perceives everything as happening smoothly/fluidly like a movie, rather than as a series of individual images being displayed to them (which will feel “janky”). A movie is still just a series of still images, but when those still images are displayed quickly enough our brains kind of fill in the blanks and don’t perceive the gaps in-between. We also need to make sure the browser can respond to interactions within about 80ms.

The more work we ask the browser to do (e.g. through inefficient animations or other complex operations) the less likely it is that it will be able to achieve these results. It is therefore important to understand how the browser does its work, so that you can integrate your animations into that process as efficiently as possible.

One of the key aspects of optimising for performance is avoiding causing too many “layouts” which is where the browser calculates the position/size of everything on the screen. For example, if we were to animate the height of a particular element on the page in response to scroll events coming from an <ion-content> component, this would cause a bit of a disaster. If we animate the height of one element, it is going to affect the position of other elements on the page, which means the browser needs to calculate the position of everything again (e.g. it will cause a “layout” or “reflow”). Not only are we causing layouts, but we are also triggering these layouts in quick succession since scroll events are fired off very rapidly. This is a scenario which might be referred to as layout thrashing where we are basically bombarding the browser rendering process with expensive work.

We are going to talk about some aspects of this throughout this article, but it is a good idea to have a general understanding of the browser rendering process. Having a better understanding of the browser rendering process will also help you design more performant applications in general, as well as helping you create performant animations.

2. Use CSS Transitions

Now we are going to get into the actual animation tips - remember that the point of these tips is focusing on the simple things we can do that can create impressive effects with little to no performance cost. Animations can seem complex and difficult to create, but you can create suprisingly impressive animations with very little work.

One of the easiest ways you can create animations in your applications is to use the CSS transition property. You can quite simply do this:

.some-element{transition: 1s linear;}

Now any time that an animatable property changes on the element that has the transition property, it will animate the change instead of just instantly changing. If the opacity property were to change from 0 to 1, the element would smoothly fade in over 1 second rather than instantly appearing. If you get creative, you can create some impressive animations with this simple concept - it is generally what I use to create most of the animations I add to my Ionic applications.

You can apply a generic transition property that will target any property changes, or you can target properties specifically:

.some-element{transition: opacity 1s linear;}

Now only opacity changes would be animated. You can also play around with the easing functions which control how the animation plays. Above we have used a “linear” easing function which will play the animation evenly over the 1 second, but you can use different timings that will cause the animation to play faster/slower at certain points of the animation. This can help add a bit of “character” to the animation, making it feel more sleek/smooth or perhaps fun/bouncy. Animations can drastically affect the mood of your application.

IMPORTANT: When it comes to animating CSS properties, not all properties are created equal in terms of performance. Although we can achieve lots of interesting things by animating the many different CSS properties that are animatable, we should generally try to only use a few of them which we will discuss now.

3. Use Transforms

The transform property is something that I rely on a lot to create animations. We can supply different values to the CSS transform property to do things like rotate, scale, and translate elements on the page. A rotate transform will rotate the element to the degree value you specify, a scale transform will make an element smaller or larger, and a translate transform will change the position of the element.

This is a concept I have made use of if both of my UI Challenge videos to scale the cart button as we saw above:

Episode #2 of my UI Challenge series is up! This time we live code an expanding button screen transition animation for @ionicframework and cover:

✅ Animating with Transforms
✅ Page Transition Animations
✅ CSS Variables
✅ Sneaky Tricks

Full video 👉 https://t.co/Vk7hva794fpic.twitter.com/IrtT2GPA1t

— Josh Morony (@joshuamorony) November 19, 2019

and to translate the position of the content area (so that it moves up when the user scrolls down):

Watch as I attempt to live code a fancy animated card layout in @Ionicframework and @angular. This one has all sorts of juicy stuff like:

✅ Shadow DOM
✅ CSS Variables
✅ CSS Animations
✅ Intersection Observer API
✅ Silly Mistakes

Full video 👉 https://t.co/3Zi87eC10qpic.twitter.com/JqybmeiFMJ

— Josh Morony (@joshuamorony) November 12, 2019

The fantastic thing about transforms is that they don’t affect the position of other elements on the page, which means it is cheap for the browser to perform. If we changed the width/height of an element to make it bigger it would be a big drain on performance, however if we scale it to make it bigger it will perform very well. That means that we have the ability to spin things, move things, or shrink/grow them (maybe all at the same time) all without having much of an impact on performance.

4. Use Opacity

Another thing that is easy for the browser to animate that can create some interesting effects is opacity. This can be used to create animations as simple as something appearing on the screen, but it can also be used to create more complex effects like the screen transition animation above, as well as this shared element transition effect:

5. Avoid everything else

The properties we have discussed above are things that we can animate without having to worry too much about wrecking performance. That doesn’t mean that we can’t also animate other properties as well, but you should be much more careful and check how much it is impacting performance by using the browser performance profiling tools. Animating things like margin and height is going to be a lot more costly than transforms and opacity - especially if the animation is happening in response to something like scroll events that are triggered fast and often.

6. Add/Remove a Class

Now we are going to get more into how to actually apply the animations - again, focusing on keeping things reasonably simple. With CSS transitions, all we need to happen is for the CSS property to change (e.g. changing the opacity property on an element from 1 to 0). One way we can do this is by applying or removing a CSS class on an element. Once the class is added or removed, the animation will play (assuming that the element has the transition property added to it).

7. Manually modify a style to apply an animation

As well as using classes to change the value of a CSS property, we can also just modify it directly. For example, we could just do something like this:

const fab =this.el.querySelector("ion-fab");
fab.style.transform ="scale3d(35,35,1)";

Exactly how you go about modifying styles through JavaScript might depend on the framework that you are using (in Angular for example you would want to use the Renderer), but this is the code I used in my Ionic/StencilJS example for the expanding button page transition. Since the button had the transition property applied to it, the animation could be triggered within the JavaScript code by directly modifying the style property.

Modifying styles as part of some kind of complex application logic can lead to some much more interesting animations.

8. Use CSS Keyframes

If it isn’t enough to just simply change a property and have that change animate, you can also use CSS keyframes to define an animation. This will allow you to easily define multiple properties and what they should change from and to - you can even define what certain properties should be at a certain percentage of the way through an animation. For example, let’s suppose you were animating a translate transform. Rather than just shifting the element 100px to the left and animating back to its normal position, maybe you want the element to fly past its final resting position halfway through the animation and then settle back into the final position to create a bit more motion. This can be achieved with keyframes.

9. Use SVGs

Scalable Vector Graphics (SVG) are an animation super power for the web. If you are unfamiliar with vector graphics, it is an image that is defined mathematically such that it can be scaled without losing quality. However, an SVG brings much more to the table than the ability to scale. An SVG has its own DOM structure (you can literally copy and paste the code for an SVG directly into your application if you want), and that DOM can be manipulated and animated just like the rest of your application. There is a lot to learn about how to create and use SVGs, but the possibilities are endless. The entire SVG is defined in that DOM structure, and we can manipulate/animate whatever we like within that DOM.

Keeping the same performance concepts in mind, we can create many impressive animations in Ionic applications with the help of SVGs. Here is one example from a tutorial I wrote a little while ago:

It uses SVGs to animate the background to reflect the current weather conditions. You can check out the full tutorial here: Animating a Dynamic Background with an SVG in Ionic.

10. Use what the framework provides

Finally, make sure you aren’t missing something obvious. Ionic provides us with a lot out of the box, so before you start building out your own custom solution make sure to check if there are any Ionic components or APIs that suit your needs. The <ion-modal> component allows you to supply a custom enterAnimation and leaveAnimation, and the <ion-nav> component can also be configured with custom animations. There are the <ion-spinner> and <ion-progress-bar> components both of which serve as animated progress indicators. We have the <ion-skeleton-text> which can also be configured as an animated placeholder for content.

Constantly improving the user interface of Ionic applications seems to be a goal of the Ionic team, so always keep an eye out for further improvements and innovations are animations in Ionic applications.

Summary

There is a lot more that can be achieved with animations, and many more ways we can do it. We haven’t even discussed the Web Animations API or any of the many different libraries out there that can help with animations, but the main point of this article was to cover some simple tips for how you can relatively easily create impressive animations without negatively affecting the performance of your application.

I’ve been with my wife since around the time Tinder was created, so I’ve never had the experience of swiping left or right myself. For whatever reason, swiping caught on in a big way. The Tinder animated swipe card UI seems to have become extremely popular and something people want to implement in their own applications. Without looking too much into why this provides an effective user experience, it does seem to be a great format for prominently displaying relevant information and then having the user commit to making an instantaneous decision on what has been presented.

Creating this style of animation/gesture has always been possible in Ionic applications - you could use one of many libraries to help you, or you could have also implemented it from scratch yourself. However, now that Ionic is exposing their underlying gesture system for use by Ionic developers, it makes things significantly simpler. We have everything we need out of the box, without having to write complicated gesture tracking ourselves.

I recently released an overview of the new Gesture Controller in Ionic 5 which you can check out below:

• Ionic 5 Preview: Create Custom Gestures (Simple Tinder Card Animation)

If you are not already familiar with the way Ionic handles gestures within their components, I would recommend giving that video a watch before you complete this tutorial as it will give you a basic overview. In the video, we implement a kind of Tinder “style” gesture, but it is at a very basic level. This tutorial will aim to flesh that out a bit more, and create a more fully implemented Tinder swipe card component.

We will be using StencilJS to create this component, which means that it will be able to be exported and used as a web component with whatever framework you prefer (or if you are using StencilJS to build your Ionic application you could just build this component directly into your Ionic/StencilJS application). Although this tutorial will be written for StencilJS specifically, it should be reasonably straightforward to adapt it to other frameworks if you would prefer to build this directly in Angular, React, etc. Most of the underlying concepts will be the same, and I will try to explain the StencilJS specific stuff as we go.

NOTE: This tutorial was built using Ionic 5 which, at the time of writing this, is currently in beta. If you are reading this before Ionic 5 has been fully released, you will need to make sure to install the @next version of @ionic/core or whatever framework specific Ionic package you are using, e.g. npm install @ionic/core@next or npm install @ionic/angular@next.

Before We Get Started

If you are following along with StencilJS, I will assume that you already have a basic understanding of how to use StencilJS. If you are following along with a framework like Angular, React, or Vue then you will need to adapt parts of this tutorial as we go.

If you would like a thorough introduction to building Ionic applications with StencilJS, you might be interested in checking out my book.

A Brief Introduction to Ionic Gestures

As I mentioned above, it would be a good idea to watch the introduction video I did about Ionic Gesture, but I will give you a quick rundown here as well. If we are using @ionic/core we can make the following imports:

import{ Gesture, GestureConfig, createGesture }from'@ionic/core';

This provides us with the types for the Gesture we create, and the GestureConfig configuration options we will use to define the gesture, but most important is the createGesture method which we can call to create our “gesture”. In StencilJS we use this directly, but if you are using Angular for example, you would instead use the GestureController from the @ionic/angular package which is basically just a light wrapper around the createGesture method.

In short, the “gesture” we create with this method is basically mouse/touch movements and how we want to respond to them. In our case, we want the user to perform a swiping gesture. As the user swipes, we want the card to follow their swipe, and if they swipe far enough we want the card to fly off screen. To capture that behaviour and respond to it appropriately, we would define a gesture like this:

const options: GestureConfig ={
      el:this.hostElement,
      gestureName:'tinder-swipe',
      onStart:()=>{// do something as the gesture begins},
      onMove:(ev)=>{// do something in response to movement},
      onEnd:(ev)=>{// do something when the gesture ends}};const gesture: Gesture =awaitcreateGesture(options);

    gesture.enable();

This is a bare-bones example of creating a gesture (there are additional configuration options that can be supplied). We pass the element we want to attach the gesture to through the el property - this should be a reference to the native DOM node (e.g. something you would usually grab with a querySelector or with @ViewChild in Angular). In our case, we would pass in a reference to the card element that we want to attach this gesture to.

Then we have our three methods onStart, onMove, and onEnd. The onStart method will be triggered as soon as the user starts a gesture, the onMove method will trigger every time there is a change (e.g. the user is dragging around on the screen), and the onEnd method will trigger once the user releases the gesture (e.g. they let go of the mouse, or lift their finger off the screen). The data that is supplied to us through ev can be used to determine a lot, like how far the user has moved from the origin point of the gesture, how fast they are moving, in what direction, and much more.

This allows us to capture the behaviour we want, and then we can run whatever logic we want in response to that. Once we have created the gesture, we just need to call gesture.enable which will enable the gesture and start listening for interactions on the element it is associated with.

With this idea in mind, we are going to implement the following gesture/animation in Ionic:

1. Create the Component

You will need to create a new component, which you can do inside of a StencilJS application by running:

npm run generate

You may name the component however you wish, but I have called mine app-tinder-card. The main thing to keep in mind is that component names must be hyphenated and generally you should prefix it with some unique identifier as Ionic does with all of their components, e.g. <ion-some-component>.

2. Create the Card

We can apply the gesture we will create to any element, it doesn’t need to be a card or sorts. However, we are trying to replicate the Tinder style swipe card, so we will need to create some kind of card element. You could, if you wanted to, use the existing <ion-card> element that Ionic provides. To make it so that this component is not dependent on Ionic, I will just create a basic card implementation that we will use.

Modify src/components/tinder-card/tinder-card.tsx to reflect the following:

import{ Component, Host, Element, Event, EventEmitter, h }from'@stencil/core';import{ Gesture, GestureConfig, createGesture }from'@ionic/core';

@Component({
  tag:'app-tinder-card',
  styleUrl:'tinder-card.css'})exportclassTinderCard{render(){return(<Host><divclass="header"><imgclass="avatar"src="https://avatars.io/twitter/joshuamorony"/></div><divclass="detail"><h2>Josh Morony</h2><p>Animator of the DOM</p></div></Host>);}}

We have added a basic template for the card to our render() method. For this tutorial, we will just be using non-customisable cards with the static content you see above. You may want to extend the functionality of this component to use slots or props so that you can inject dynamic/custom content into the card (e.g. have other names and images besides “Josh Morony”).

It is also worth noting that we have set up all of the imports we will be making use of:

import{ Component, Host, Element, Event, EventEmitter, h }from'@stencil/core';import{ Gesture, GestureConfig, createGesture }from'@ionic/core';

We have our gesture imports, but as well as that we are importing Element to allow us to get a reference to the host element (which we want to attach our gesture to). We are also importing Event and EventEmitter so that we can emit an event that can be listened for when the user swipes right or left. This would allow us to use our component in this manner:

<app-tinder-cardonMatch={(ev)=>{this.handleMatch(ev)}}/>

So that our cards don’t look completely ugly, we are going to add a few styles as well.

Modify src/components/tinder-card/tinder-card.css to reflect the following:

app-tinder-card{display: block;width: 100%;min-height: 400px;border-radius: 10px;display: flex;flex-direction: column;box-shadow: 0 0 3px 0px #cecece;}.header{background-color: #36b3e7;border: 4px solid #fbfbfb;border-radius: 10px 10px 0 0;display: flex;justify-content: center;align-items: center;flex: 2;}.avatar{width: 200px;height: auto;}.detail{background-color: #fbfbfb;padding-left: 20px;border-radius: 0 0 10px 10px;flex: 1;}

3. Define the Gesture

Now we are getting into the core of what we are building. We will define our gesture and the behaviour that we want to trigger when that gesture happens. We will first add the code as a whole, and then we will focus on the interesting parts in detail.

Modify src/components/tinder-card/tinder-card.tsx to reflect the following:

import{ Component, Host, Element, Event, EventEmitter, h }from'@stencil/core';import{ Gesture, GestureConfig, createGesture }from'@ionic/core';

@Component({
  tag:'app-tinder-card',
  styleUrl:'tinder-card.css'})exportclassTinderCard{

  @Element() hostElement: HTMLElement;
  @Event() match: EventEmitter;connectedCallback(){this.initGesture();}asyncinitGesture(){const style =this.hostElement.style;const windowWidth = window.innerWidth;const options: GestureConfig ={
      el:this.hostElement,
      gestureName:'tinder-swipe',
      onStart:()=>{
        style.transition ="none";},
      onMove:(ev)=>{
        style.transform =`translateX(${ev.deltaX}px) rotate(${ev.deltaX/20}deg)`},
      onEnd:(ev)=>{

        style.transition ="0.3s ease-out";if(ev.deltaX > windowWidth/2){
          style.transform =`translateX(${windowWidth *1.5}px)`;this.match.emit(true);}elseif(ev.deltaX <-windowWidth/2){
          style.transform =`translateX(-${windowWidth *1.5}px)`;this.match.emit(false);}else{
          style.transform =''}}};const gesture: Gesture =awaitcreateGesture(options);

    gesture.enable();}render(){return(<Host><divclass="header"><imgclass="avatar"src="https://avatars.io/twitter/joshuamorony"/></div><divclass="detail"><h2>Josh Morony</h2><p>Animator of the DOM</p></div></Host>);}}

At the beginning of this class, we have set up the following code:

  @Element() hostElement: HTMLElement;
  @Event() match: EventEmitter;connectedCallback(){this.initGesture();}

The @Element() decorator will provide us with a reference to the host element of this component. We also set up a match event emitter using the @Event() decorator which will allow us to listen for the onMatch event to determine which direction a user swiped.

We have set up the connectedCallback lifecycle hook to automatically trigger our initGesture method which is what handles actually setting up the gesture. We have already discussed the basics of defining a gesture, so let’s focus on our specific implementation of the onStart, onMove, and onEnd methods:

      onStart:()=>{
        style.transition ="none";},
      onMove:(ev)=>{
        style.transform =`translateX(${ev.deltaX}px) rotate(${ev.deltaX/20}deg)`},
      onEnd:(ev)=>{

        style.transition ="0.3s ease-out";if(ev.deltaX > windowWidth/2){
          style.transform =`translateX(${windowWidth *1.5}px)`;this.match.emit(true);}elseif(ev.deltaX <-windowWidth/2){
          style.transform =`translateX(-${windowWidth *1.5}px)`;this.match.emit(false);}else{
          style.transform =''}}

Let’s being with the onMove method. When the user swipes on the card, we want the card to follow the movement of that swipe. We could just detect the swipe and animate the card after the swipe has been detected, but this isn’t as interactive and won’t look as nice/smooth/intuitive. So, what we do is modify the transform property of the elements style to modify the translateX to match the deltaX of the movement. The deltaX is the distance the gesture has moved from the initial start point in the horizontal direction. The translateX will move an element in a horizontal direction by the number of pixels we supply. If we set this translateX to the deltaX it will mean that the element will follow our finger, or mouse, or whatever we are using for input along the screen.

We also set the rotate transform so that the card rotates in relation to a ratio of the horizontal movement - the further you get to the edge of the screen, the more the card will rotate. This is divided by 20 just to lessen the effect of the rotation - try setting this to a smaller number like 5 or even just use ev.deltaX directly and you will see how ridiculous it looks.

The above gives us our basic swiping gesture, but we don’t want the card to just follow our input - we need it to do something after we let go. If the card isn’t near enough the edge of the screen it should snap back to its original position. If the card has been swiped far enough in one direction, it should fly off the screen in the direction it was swiped.

First, we set the transition property to 0.3s ease-out so that when we reset the cards position back to translateX(0) (if the card was no swiped far enough) it doesn’t just instantly pop back into place - instead, it will animate back smoothly. We also want the cards to animate off screen nicely, we don’t want them to just pop out of existence when the user lets go.

To determine what is “far enough”, we just check if the deltaX is greater than half the window width, or less than half of the negative window width. If either of those conditions are satisfied, we set the appropriate translateX such that the card goes off the screen. We also trigger the emit method on our EventListener so that we can detect the successful swipe when using our component. If the swipe was not “far enough” then we just reset the transform property.

One more important thing we do is set style.transition = "none"; in the onStart method. The reason for this is that we only want the translateX property to transition between values when the gesture has ended. There is no need to transition between values onMove because these values are already very close together, and attempting to animate/transition between them with a static amount of time like 0.3s will create weird effects.

4. Use the Component

Our component is complete! Now we just need to use it, which is reasonably straight-forward with one caveat which I will get to in a moment. Using the component directly in your StencilJS application would look something like this:

import{ Component, h }from'@stencil/core';

@Component({
  tag:'app-home',
  styleUrl:'app-home.css'})exportclassAppHome{handleMatch(ev){if(ev.detail){
      console.log("It's a match!")}else{
      console.log("Maybe next time");}}render(){return[<ion-header><ion-toolbarcolor="primary"><ion-title>Ionic Tinder Cards</ion-title></ion-toolbar></ion-header>,<ion-contentclass="ion-padding"><divclass="tinder-container"><app-tinder-cardonMatch={(ev)=>{this.handleMatch(ev)}}/><app-tinder-cardonMatch={(ev)=>{this.handleMatch(ev)}}/><app-tinder-cardonMatch={(ev)=>{this.handleMatch(ev)}}/></div></ion-content>];}}

We can mostly just drop our app-tinder-card right in there, and then just hook up the onMatch event to some handler function as we have done with the handleMatch method above.

One thing we have not covered in this tutorial is handling a “stack” of cards, as these Tinder cards would usually be used in. What would likely be the nicer option is to create an additional <app-tinder-card-stack> component, such that it could be used like this:

<app-tinder-card-stack><app-tinder-card/><app-tinder-card/><app-tinder-card/></app-tinder-card-stack>

and the styling for positioning the cards on top of one another would be handled automatically. However, for now, I have just added some manual styling directly in the page to position the cards directly:

.tinder-container{position: relative;}app-tinder-card{position: absolute;top: 0;left: 0;}

Which will give us something like this:

Summary

It’s pretty fantastic to be able to build what is a reasonably cool/complex looking animated gesture, all with what we are given out of the box with Ionic. The opportunities here are effectively endless, you could create any number of cool gestures/animations using the basic concept of listening for the start, movement, and end events of gestures. This is also using just the bare-bones features of Ionic’s gesture system as well, there are more advanced concepts you could make use of (like conditions in which a gesture is allowed to start).

I wanted to focus mainly on the gestures and animation aspect of this functionality, but if there is interest in covering the concept of a <app-tinder-card-stack> component to work in conjunction with the <app-tinder-card> component let me know in the comments.

In my recent tutorials, I have been explaining how to build more complex UI/UX patterns into Ionic applications with the Ionic Animations API and the improved gesture support in Ionic 5. I often keep a look out for impressive gestures or animations whether they are in traditional “native” mobile applications, or just a designers concept, and see if I can implement something the same or similar in Ionic.

My goal is to help dispel the perception that interesting interactions and animations are for the realm of native mobile applications that use native UI controls, as opposed to Ionic applications which use a web view to power the UI (which I think is actually one of Ionic’s greatest advantages). With a bit of knowledge about how to go about designing complex gestures and animations in a web environment, we can often create results that are indistinguishable from a native user interface.

That is why I decided to tackle building the Swipe to Archive feature that the Gmail mobile application uses in Ionic. The basic idea is that you can swipe any of the emails in your inbox, and if you swipe far enough the email will be archived. As you swipe, and icon is revealed underneath that implies the result of the gesture. If you do not swipe far enough, then the email will slide back into it’s normal resting place. It looks like this:

Building this in Ionic is similar in concept to the Tinder Swipe Cards I created recently, but there are some interesting differences. For the Tinder cards, we rely entirely on Ionic’s Gesture system, but in this tutorial we will be making use of both the Gestures system and the Ionic Animations API.

Some interesting challenges that we will solve in this tutorial include:

• Creating an entirely self contained component to perform the functionality
• Making an element follow a gesture on the screen
• Detecting an archive/don’t-archive threshold from the gesture
• Chaining animations such that one animation plays only after another has finished
• Creating a complex delete animation which gives an element time to “animate away” before physically being deleted
• Using CSS grid to place elements on top of one another

We will be building this as a StencilJS component inside of an Ionic/StencilJS application, but this tutorial could also be used to build the same functionality into Angular, React, or Vue with a few tweaks. I will do my best to highlight the StencilJS specific concepts as we go.

The end result will look like this:

NOTE: This tutorial was built using Ionic 5 which, at the time of writing this, is currently in its release candidate stage. If you are reading this before Ionic 5 has been fully released, you will need to make sure to install the @next version of @ionic/core or whatever framework specific Ionic package you are using, e.g. npm install @ionic/core@next or npm install @ionic/angular@next.

Before We Get Started

If you are following along with StencilJS, I will assume that you already have a basic understanding of how to use StencilJS. If you are following along with a framework like Angular, React, or Vue then you will need to adapt parts of this tutorial as we go.

If you would like a thorough introduction to building Ionic applications with StencilJS, you might be interested in checking out my book.

If you do not already have a basic understanding of the Ionic Animations API or Gestures I would recommend familiarising yourself with the following resources first:

• Introduction to Ionic Gestures with Tinder Cards
• Introduction to the Ionic Animations API

1. The Basic Component Structure and Layout

You will need to first create a new component for whatever you are using to build your application, but if you are using StencilJS as I am in this tutorial you can run the following command to help create it:

npm run generate

I named my component app-swipe-delete but you can use whatever you like. Let’s get the basic structure of the component implemented first, and then we will add on the gesture and animation functionality.

Modify the component to reflect the following:

import{ Component, Host, Element, Event, EventEmitter, h }from'@stencil/core';import{ Gesture, GestureConfig, createGesture, createAnimation }from"@ionic/core";

@Component({
  tag:'app-swipe-delete',
  styleUrl:'swipe-delete.css'})exportclassSwipeDelete{

  @Element() hostElement: HTMLElement;
  @Event() deleted: EventEmitter;private gesture: Gesture;asynccomponentDidLoad(){const innerItem =this.hostElement.querySelector('ion-item');const style = innerItem.style;const windowWidth = window.innerWidth;}disconnectedCallback(){if(this.gesture){this.gesture.destroy();this.gesture =undefined;}}render(){return(<Hoststyle={{display:`grid`, backgroundColor:`#2ecc71`}}><divstyle={{gridColumn:`1`, gridRow:`1`, display:`grid`, alignItems:`center`}}><ion-iconname="archive"style={{marginLeft:`20px`, color:`#fff`}}></ion-icon></div><ion-itemstyle={{gridColumn:`1`, gridRow:`1`}}><slot></slot></ion-item></Host>);}}

We have set up all of the imports that we need for this component, which includes what is required for creating gestures and using the Ionic Animations API. If you are using Angular, keep in mind that you can import the GestureController from @ionic/angular and use that instead of createAnimation.

We use @Element() to grab a reference to the node that represents the element we are creating in the DOM - if you are not using StencilJS you would need to grab a reference to the DOM element in some other way. We also use @Event() to set up a deleted event which is another StencilJS specific concept, but is also achievable in other ways frameworks like Angular and React. Basically, we want to at some point indicate that the element has been deleted, and we will listen for that event outside of the component to determine when to remove its data from the application (e.g. when to remove the corresponding item from the array that contains everything in our list).

In the componentDidLoad lifecycle hook which runs automatically when the component has loaded, we set up some more references to values we will need to define the gesture and animations. We will be animating the items to the right side of the screen, but an important thing to keep in mind is that we don’t want to move the entire component. The component will be comprised of two blocks sitting on top of each other - the block behind will remain in place (and will display a little “archive” icon) and the block on top will slide to the right. To achieve this, we grab a reference to the <ion-item> that will live inside of this component so that we can manipulate it later. We also grab a reference to the width of the screen so that we know how far to the right we need to animate the <ion-item> when it is being deleted.

The disconnectedCallback just runs some clean up code for when the component is destroyed. Then we have the template itself. Inside of our component we have an <ion-item> and a generic <div>. We want the <div> to display the background colour and the icon, and we want the <ion-item> to sit on top of that to display the regular content. To get these two elements sitting on top of one another we need to start getting a little tricky. We could achieve this with some absolute positioning, but that will make some other things like positioning the archive icon the way we want awkward. Instead, we are using a little CSS Grid trick to position the elements on top of each other. We use display: grid to make use of CSS Grid, and then we tell both elements to occupy the same grid-column and grid-row. Then in our <div> we can just use align-items: center to get our <ion-icon> to be vertically aligned.

The only other thing we are doing here is using a <slot> inside of the <ion-item>. The basic idea of a slot is that it will project content supplied to the component inside of the component itself (if you are familiar with Angular’s <ng-content> it is pretty much the same thing). What this means is that if we use the component like this:

<app-swipe-delete>
	Hello there
</app-swipe-delete>

That content would be projected inside of our component like this:

<divstyle={{gridColumn:`1`, gridRow:`1`, display:`grid`, alignItems:`center`}}><ion-iconname="archive"style={{marginLeft:`20px`, color:`#fff`}}></ion-icon></div><ion-itemstyle={{gridColumn:`1`, gridRow:`1`}}>
  Hello there
</ion-item>

If you would like to read more about how slots work, you can take a look at the following article:

• Understanding How Slots are Used in Ionic

NOTE: We are using an <ion-item> here to make use of the default Ionic styling, but you could just as easily build this with another generic <div> instead of <ion-item> if you didn’t want this component to be dependent on Ionic.

2. Setting up the Gesture

Now let’s work on the gesture. What we want to do is be able to swipe the list item elements and have the element follow our finger. If the element is swiped/dragged far enough, then it will perform a delete animation.

Modify the load lifecycle hook to reflect the following:

asynccomponentDidLoad(){const innerItem =this.hostElement.querySelector('ion-item');const style = innerItem.style;const windowWidth = window.innerWidth;const options: GestureConfig ={
      el:this.hostElement,
      gestureName:'swipe-delete',onStart:()=>{
        style.transition ="";},onMove:(ev)=>{if(ev.deltaX >0){
          style.transform =`translate3d(${ev.deltaX}px, 0, 0)`;}},onEnd:(ev)=>{
        style.transition ="0.2s ease-out";if(ev.deltaX >150){
          style.transform =`translate3d(${windowWidth}px, 0, 0)`;}else{
          style.transform =''}}}this.gesture =awaitcreateGesture(options);this.gesture.enable();}

This gesture is almost identical to the one we created in the Tinder card tutorial, so if you would like some more elaboration I would recommend giving that tutorial a read. The basic idea is that we translate the element in the X direction for whatever the deltaX value of the gesture is. The deltaX value represents how far in the horizontal direction the users finger/mouse/whatever has moved from the origin point of the gesture. If we use transform: translate to move our element the same amount as the deltaX then it will follow the users input on the screen. We also use the onEnd method once the gesture has been completed to determine if the gesture was swiped far enough to trigger a delete/archive (i.e. was the final deltaX value above 150?). If it was swiped far enough, then we automatically animate the item all of the way off of the screen by setting the translate value on the X-axis to the windowWidth value.

An important difference with this gesture, as opposed to the Tinder cards, is that we are listening for the gesture on the host element of the component but we are actually animating one of the inner items of the component - the <ion-item> that is inside of the component. As I mentioned, we don’t want to move the entire component over as we need part of it to stay in place to display the background colour and the archive icon.

3. Implementing the Leave Animation

We have already created our gesture and have the item animating off screen if the item was swiped far enough, but there are still a couple more things that we need to do. Once the item has animated off screen, we don’t want the green block sitting behind that item and displaying the archive icon to just sit there indefinitely, we will want that to animate away as well. On top of that, once is has finished animating away we want to trigger the delete event so that we know we can now delete that element for real (rather that just hiding it away through animations).

It is important that we wait until the animation has finished before triggering that delete event, otherwise our animation will get cut off. The Ionic Animations API provides an easy was to do this, as we can use the onFinish method to trigger some code once an animation has completed.

Modify the load lifecycle hook to reflect the following:

asynccomponentDidLoad(){const innerItem =this.hostElement.querySelector('ion-item');const style = innerItem.style;const windowWidth = window.innerWidth;const hostDeleteAnimation =createAnimation().addElement(this.hostElement).duration(200).easing('ease-out').fromTo('height','48px','0');const options: GestureConfig ={
      el:this.hostElement,
      gestureName:'swipe-delete',onStart:()=>{
        style.transition ="";},onMove:(ev)=>{if(ev.deltaX >0){
          style.transform =`translate3d(${ev.deltaX}px, 0, 0)`;}},onEnd:(ev)=>{
        style.transition ="0.2s ease-out";if(ev.deltaX >150){
          style.transform =`translate3d(${windowWidth}px, 0, 0)`;

          hostDeleteAnimation.play()

          hostDeleteAnimation.onFinish(()=>{this.deleted.emit(true);})}else{
          style.transform =''}}}this.gesture =awaitcreateGesture(options);this.gesture.enable();}

Now we have defined a hostDelete animation that will animate the height of the entire component from 48px to 0, which means it will shrink away just as the Gmail delete animation does. It is important to note that animating a property like height can be expensive for performance (basically you should only animate transform and opacity wherever possible to achieve your animations). Depending on the context, you might want to profile the performance of this animation to make sure it suits your needs. A higher performance version of this animation could be achieved by animating the opacity to hide the host element rather than height but it wouldn’t be quite as nice. Another limitation of this animation is that it requires a fixed/known height to animate from.

Then all we do is trigger this animation with the play() method inside of our onEnd method if appropriate. The cool part here is that we then also add an onFinish callback for that animation, so that when it is finished it will trigger this.delete.emit(true).

4. Using the Component

Now that we have our component created, let’s take a look at how to use it and how to listen for that deleted event so that we can remove the items data from the list at the appropriate time. Again, this example will be for StencilJS but the same basic principles will apply elsewhere.

import{ Component, State, h }from'@stencil/core';

@Component({
  tag:'app-home',
  styleUrl:'app-home.css'})exportclassAppHome{

  @State() items =[];componentWillLoad(){this.items =[{uid:1, subject:'hello', message:'hello'},{uid:2, subject:'hello', message:'hello'},{uid:3, subject:'hello', message:'hello'},{uid:4, subject:'hello', message:'hello'},{uid:5, subject:'hello', message:'hello'},{uid:6, subject:'hello', message:'hello'},{uid:7, subject:'hello', message:'hello'},{uid:8, subject:'hello', message:'hello'},{uid:9, subject:'hello', message:'hello'},{uid:10, subject:'hello', message:'hello'}]}render(){return[<ion-header><ion-toolbarcolor="primary"><ion-title>Home</ion-title></ion-toolbar></ion-header>,<ion-content><ion-list>{this.items.map((item)=>(<app-swipe-deletekey={item.uid}onDeleted={()=>this.handleDelete(item.uid)}>{item.subject}</app-swipe-delete>))}</ion-list></ion-content>];}handleDelete(uid){this.items =this.items.filter((item)=>{return item.uid !== uid;});this.items =[...this.items];}}

All we need to do now to make use of this component is to loop over an array of data and use our <app-swipe-delete> component for each element. We can supply it with whatever content we want to display inside of the item, and we can also listen for the deleted event to handle removing the item from the list when necessary. To do that in StencilJS we use onDeleted, but this might look slightly different depending on what you are using.

The end result should look something like this:

Summary

What we have created is a reasonably advanced interaction/animation, but with the use of Ionic’s gesture system and the Ionic Animations API it is actually reasonably smooth to create with relatively little code. There is a lot you could do and create with reasonably minor variations on the general concepts we have made use of in this tutorial.

There are many instances in which we can use a staggered animation in our applications, but it is perhaps most commonly used with lists or thumbnails/galleries. The idea is that we apply an animation (usually the same animation) to multiple elements, but we execute those animations with an increasing amount of delay for each element.

The result is an appearance that these individual animations are linked together, creating a kind of “flow” of elements animating on to the screen (or some other kind of animation). I recently published a video that walks through creating this effect in Ionic if you would like to see an example of what I am talking about:

There can be a practical purpose to this style of animation - in that it could be used to give a sense of direction (e.g. the list flows downwards and there is more content to discover below) or even as a mechanism to create “perceived performance” whilst loading - but for the most part, it just generally looks/feels nice (as long as the animation isn’t too slow).

The basic concept is simple enough, we create an animation:

@keyframes popIn{0%{opacity: 0;transform:scale(0.6)translateY(-8px);}100%{opacity: 1;transform: none;}}

and then apply that animation to each element in our list:

ion-item{animation: popIn 0.2s both ease-in;}

The trick is to add an animation-delay so that the animations don’t all trigger at once, e.g:

ion-item{animation: popIn 0.2s 70ms both ease-in;}

The animation now has a delay of 70ms which means the browser will wait 70ms before starting the animation. However, this will apply the same delay to every item in the list, which is not what we want. We want the first ion-item to have no delay, the second to have 70ms of delay, the third to have 140ms of delay and so on.

Instead, we can do something like this:

ion-item:nth-child(1){animation-delay: 70ms
}ion-item:nth-child(2){animation-delay: 140ms
}ion-item:nth-child(3){animation-delay: 210ms
}

This will achieve what we want, but you can see how this would quickly become tiresome to write and maintain, even for small lists. To make the process of writing out each of these rules above easier, it is common to use SASS which is a preprocessor for CSS that will allow us to write loops to create rules like the above automatically (e.g. we could create 50 nth-child rules with one loop in SASS).

This works, but there are some downsides. It is still a bit tricky to write out the loop, if you don’t know how many items will be in your list then SASS might create a bunch of unnecessary rules for items that don’t exist, or maybe you just don’t know how to use SASS or you don’t want to use it.

Staggered Animations without SASS

SASS was the way I would typically achieve staggered animations, but I started searching around for solutions that wouldn’t require any additional dependencies. As it turns out, it is possible to achieve this style of animation entirely with CSS.

In my research, I came across the following article by Daniel Benmore: Different Approaches for Creating a Staggered Animation. Daniel was searching for the same thing I was, and he came to a solution which I think is genius in its simplicity. We can do everything we need just with CSS Variables.

I’ve written a lot on the subject of CSS variables and Ionic before, so if you need a bit of background information you might be interested in the following articles:

• A Primer on CSS 4 Variables for Ionic
• Creating a Theme Switcher Service in Ionic Using CSS4 Variables

The video I published above walks through adapting the concept Daniel talks about into an Ionic application with a list of a dynamic size. The example is created inside of an Ionic/StencilJS application, but the same concepts can be used with Angular, React, or Vue as well (just with a bit of tweaking for syntax).

One of the commenters on the video pointed out that the example with CSS variables would not work for an infinite list in Ionic. This is true, but with a small change the same concept can also be applied to infinite lists.

In this tutorial, I am going to walk through implementing the basic example that is already covered in the video, and then how we can modify that implementation so that it will work with an infinite list as well.

Before We Get Started

If you are following along with StencilJS, I will assume that you already have a basic understanding of how to use StencilJS. If you are following along with a framework like Angular, React, or Vue then you will need to adapt parts of this tutorial as we go.

If you would like a thorough introduction to building Ionic applications with StencilJS, you might be interested in checking out my book.

1. Animating a Static List

The key idea behind the CSS variable approach is that we attach a CSS variable to each element through the style attribute that represents its order in the list. The order of the element in the list is used to calculate its animation-delay - items later in the list will have larger animation delays. We name this CSS variable --animation-order in this example, but it could be named whatever you like.

Just as was the case with the SASS example, we could apply this manually to each element, e.g:

<ion-list><ion-itemstyle="--animation-order: 0">One</ion-item><ion-itemstyle="--animation-order: 1">Two</ion-item><ion-itemstyle="--animation-order: 2">Three</ion-item></ion-list>

But this is awkward and doesn’t work well with dynamic lists. What we can do instead is assign its value based on its position (index) in the array of values we are looping over for the list. In StencilJS (and React) that would look something like this:

render(){return[<ion-header><ion-toolbarcolor="primary"><ion-title>Home</ion-title></ion-toolbar></ion-header>,<ion-content><ion-listlines="none">{this.items.map((item, index)=>(<ion-itemstyle={{"--animation-order": index }as any}><ion-label>{item}</ion-label></ion-item>))}</ion-list></ion-content>];}

We use the index in the loop to determine what the --animation-order should be. Since StencilJS uses TSX for the template (i.e. JSX with TypeScript) we also need to add as any since we don’t have a type for our CSS variable. In Angular, you would use an *ngFor loop instead of a map.

With an animation order assigned to each item in the list, the animation just becomes a matter of using that value to calculate the animation delay:

ion-item{animation: popIn 0.2s calc(var(--animation-order) * 70ms) both ease-in;}@keyframes popIn{0%{opacity: 0;transform:scale(0.6)translateY(-8px);}100%{opacity: 1;transform: none;}}

The CSS above would give the element with an --animation-order of 0 an animation-delay of 0 * 70ms which is 0ms. The element with an --animation-order of 1 would have a delay of 1 * 70ms which is 70ms, and so on for each element in the list.

2. Animating an Infinite List

This method could work even for lists with 100s of items. The problem that an infinite list introduces is that not all of the items are loaded at the same time, instead, more items are loaded each time the user gets to the bottom of the list.

If we load in 10 items initially, and then another 10 when we get to the bottom of the list, we don’t want the 11th item in the list to have a delay 70ms longer than the 10th item - we want the 11th item to have no delay since we want it to animate on screen as soon as the additional items load, and then we want the 12th item to have 70ms of delay just like the 2nd item had. Basically, we want to reset the delays.

This issue sounds like it could be a bit tricky, but there is actually a very simple solution. All you need to do is use the following:

<ion-itemstyle={{"--animation-order":index%10}asany}>

We use the modulo operator (%) to return the remainder when the index is divided by 10 - you just need to change 10 to whatever your “page size” is (e.g. how many new items you load for each infinite load trigger). This can also be set dynamically. Let’s take the 12th item as an example. The 12th item in the list would have an index of 11 (since the index begins at 0). If we divide 11 by 10 (our page size) we will have a remainder of 1, which is what the modulo operator will return to us and use as the value for --animation-order.

Now when calculating the animation delay for the 12th item, we will have 1 * 70ms which is a delay of 70ms - exactly what we want. Here is an example with some dummy data loading in that you can try out for yourself (again, this is a StencilJS example):

import{ Component, State, Listen, h }from"@stencil/core";

@Component({
  tag:"app-home",
  styleUrl:"app-home.css"})exportclassAppHome{
  @State() items: string[]=[];componentWillLoad(){this.items =["one","two","three","four","five","six","seven","eight","nine","ten"];}

  @Listen("ionInfinite")loadData(event){setTimeout(()=>{
      console.log("Done");this.items.push("one","two","three","four","five","six","seven","eight","nine","ten");this.items =[...this.items];
      event.target.complete();// App logic to determine if all data is loaded// and disable the infinite scrollif(this.items.length >100){
        event.target.disabled =true;}},1000);}render(){return[<ion-header><ion-toolbarcolor="primary"><ion-title>Home</ion-title></ion-toolbar></ion-header>,<ion-content><ion-listlines="none">{this.items.map((item, index)=>(<ion-itemstyle={{"--animation-order": index %10}as any}><ion-label>{item}</ion-label></ion-item>))}</ion-list><ion-infinite-scrollthreshold="100px"><ion-infinite-scroll-contentloading-spinner="bubbles"loading-text="Loading more data..."></ion-infinite-scroll-content></ion-infinite-scroll></ion-content>];}}

Summary

I am thrilled to have come across this method because I think that it is both more efficient and easier to execute than the SASS example, not to mention that it also doesn’t require installing and setting up SASS in your project. Thanks to Daniel Benmore for the fantastic concept!

When animating the size or position of elements in our applications, we should (generally) only use the transform property to achieve this. Animating anything else - like width, height, margin, position, and padding - will result in triggering a browser “layout”. This is where the browser needs to recalculate the positions of everything on the screen, which is the most expensive step in the browser rendering process in terms of performance. If we trigger this process many times in quick succession (by animating a change in these properties) we can quickly destroy the performance of the application. The extra work the browser needs to do to calculate the positions will result in slower “frames” (i.e. the result being shown to the user on screen), and if we can not achieve around 60 frames per second the animation will not feel smooth.

The reason this step is necessary for most position affecting properties is that one element changing will affect the position of other elements of the screen (e.g. reducing the height of an element will cause other elements on the screen to shift upwards). The reason that the transform property performs so well is that it doesn’t trigger layouts (or even “paints”) in the browser rendering process. Modifying the transform property will only trigger the last step in the browser rendering process. This is where the “compositor” organises/positions/scales “layers” on the screen - all the heavy calculation work is already done and the various “layers” have their results painted onto them already, the work of the compositor is kind of like shuffling papers around. Less work for the browser to do means faster frames, and faster frames means smoother animations.

But! This is somewhat limiting. The transform property can do a lot like scale, rotate, and translate to modify an element, but sometimes we might want to make use of other positional properties in our animations. Expanding an element to be full screen is a lot easier if we can use position to calculate the new dimensions.

FLIP (First, Last, Invert, Play)

This is where the FLIP concept comes in. FLIP is an acronym that stands for:

• First - calculate the current positions on the screen
• Last - calculate the final positions on the screen
• Invert - use transforms to modify the final positions to immitate the first positions
• Play - play the animation by removing the transforms

This concept relies on the fact that a user won’t perceive that something hasn’t happened as long as we respond to their input in around 100ms. That means that we can use that initial 100ms before anything happens on screen to perform heavy calculations for the animation, and then play the animation smoothly with transforms.

Let’s consider the example where we want to use position to animate an element to another position on the screen. We can’t use position directly for the animation as it will result in poor performance (since it will trigger layouts throughout the animation). However, what we can do is this:

• First - use getBoundingClientRect() to determine the current position of the element
• Last - apply a class to the element that applies the appropriate position styles (with no animations) and then use getBoundingClientRect() to determine the new position of the element.
• Invert - use the two position values to calculate what transform values need to be applied to get the element in its final position, transformed back to its original position
• Play - now that we have done all the calculations, we can play the animation by animating the transform back to its initial state (e.g. transform: scale(1, 1) translate(0, 0))

If you would like a more thorough introduction to using FLIP in Ionic I have a more in-depth video available: Improve Animation Performance with FLIP and the Ionic Animations API. You can also check out the original post (at least, I think it is the original) on this concept by Paul from the Google Chrome team: FLIP Your Animations.

This style of animation is great for situations where you need to dynamically calculate position values for animations, like for expanding elements to be full screen (which is what I cover in the video above).

However, I also wanted to demonstrate using this concept in another context that is also useful and not just expanding something to be a certain size on the page. In this tutorial, we will create an add-to-cart animation that will have the image for the product shrink and fly to the cart icon on the screen. We will be doing this by creating a generic component that will allow you to supply any element on the screen and have the product image fly dynamically to that position on the screen (no matter where it is). This is what it will look like:

Before We Get Started

This application was created using Ionic/StencilJS, but the methods being used (e.g. the Ionic Animations API) are also available for Angular, React, Vue, etc. If you are following along with StencilJS, I will assume that you already have a reasonasble understanding of how to use StencilJS. If you are following along with a framework like Angular, React, or Vue then you will need to adapt parts of this tutorial as we go.

If you would like a thorough introduction to building Ionic applications with StencilJS, you might be interested in checking out my book.

1. The General Concept

There are a few extra little animations in play in the GIF above to make everything look a bit nicer, but the key concept behind the animation is that we have a clone of the product image transforming its size/position as it moves toward a particular element on the screen - in this case, the cart button. We could just use a static position on the screen to animate to, but we will be creating a component that allows for any element on the screen to be supplied to determine the position. This component will be called <app-fly-to> - if you are using StencilJS you could generate this component automatically by running npm run generate and naming it app-fly-to.

Using the component will look something like this:

<ion-contentclass="ion-padding">{this.cards.map((card)=>(<app-fly-to><divclass="product-card"><imgsrc="http://placehold.it/400"/><p>
                Keep close to Nature's heart... and break clear away, once in
                awhile, and climb a mountain or spend a week in the woods. Wash
                your spirit clean.
              </p><ion-buttonexpand="full"onClick={(ev)=>{this.addToCart(ev);}}>
                Add to Cart
              </ion-button></div></app-fly-to>))}</ion-content>,

addToCart(ev){const flyToElement = ev.target.closest("app-fly-to");
    flyToElement.trigger(this.cartButton);}

First, we just have a list of product cards that we are displaying in our application. To achieve the functionality we want, we will wrap our product cards in the <app-fly-to> component. This component will provide a trigger method, which will start the animation. All we need to do is get a reference to the relevant <app-fly-to> component (which we are doing inside of the addToCart method on the page) and then call its trigger method. We supply the trigger method with a reference to the element that we want the product image to fly to.

2. The Basics of the Component

Let’s first take a look at the basic structure of the <app-fly-to> component:

import{ Component, Method, Element, ComponentInterface, h }from"@stencil/core";import{ createAnimation, Animation }from"@ionic/core";

@Component({
  tag:"app-fly-to",
  styleUrl:"app-fly-to.css",})exportclassAppFlyToimplementsComponentInterface{
  @Element() hostElement: HTMLElement;

  @Method()asynctrigger(flyTo: HTMLElement){}render(){return<slot></slot>;}}

The structure is quite simple - we just have a <slot> for the template which will project any template supplied inside of the <app-fly-to> tags into the <app-fly-to> component’s template (the equivalent in Angular would be <ng-content>). If you are unfamiliar with <slot> and content projection you might want to read: Understanding How Slots are Used in Ionic.

We are also importing createAnimation which we will make use of inside of the trigger method to create our animations.

3. The FLIP Animation

Now let’s get down to business, this is what the trigger method looks like when we add in our FLIP animation to move the product image to the cart button:

  @Method()asynctrigger(flyTo: HTMLElement){const elementToAnimate =this.hostElement.querySelector("img");// Firstconst first = elementToAnimate.getBoundingClientRect();const clone = elementToAnimate.cloneNode();const clonedElement: HTMLElement =this.hostElement.appendChild(
      clone
    )as HTMLElement;// Lastconst flyToPosition = flyTo.getBoundingClientRect();
    clonedElement.style.cssText =`position: fixed; top: ${flyToPosition.top}px; left: ${flyToPosition.left}px; height: 50px; width: auto;`;const last = clonedElement.getBoundingClientRect();// Invertconst invert ={
      x: first.left - last.left,
      y: first.top - last.top,
      scaleX: first.width / last.width,
      scaleY: first.height / last.height,};// Playconst flyAnimation: Animation =createAnimation().addElement(clonedElement).duration(500).beforeStyles({["transform-origin"]:"0 0",["clip-path"]:"circle()",["z-index"]:"10",}).easing("ease-in").fromTo("transform",`translate(${invert.x}px, ${invert.y}px) scale(${invert.scaleX}, ${invert.scaleY})`,"translate(0, 0) scale(1, 1)").fromTo("opacity","1","0.5");

    flyAnimation.onFinish(()=>{
      clonedElement.remove();});

    flyAnimation.play();}

NOTE: If you are using this tutorial to understand the FLIP concept, I would recommend this video instead. This tutorial is a “less standard” implementation of FLIP.

Let’s take a look at each of the steps in the FLIP process happening here in detail.

First

const elementToAnimate =this.hostElement.querySelector("img");// Firstconst first = elementToAnimate.getBoundingClientRect();const clone = elementToAnimate.cloneNode();const clonedElement: HTMLElement =this.hostElement.appendChild(
      clone
    )as HTMLElement;

There is an additional step here that wouldn’t be typical in a FLIP animation, because we don’t want to just animate the image element itself, we want to animate a copy of the image (because we still want the product image to remain on the card as well). So, after grabbing a reference to the image, we clone it with cloneNode and append the duplicated image as another child in the component.

The actual FLIP step here is calculating the initial position of the image (its “normal” position on the card) using getBoundingClientRect which will give us the following details about the element:

x : 93
y : 50
width : 440
height : 240
top : 50
right : 533
bottom : 290
left : 93

This gives us (more than) enough information to make the position calculations we need.

Last

// Lastconst flyToPosition = flyTo.getBoundingClientRect();
    clonedElement.style.cssText =`position: fixed; top: ${flyToPosition.top}px; left: ${flyToPosition.left}px; height: 50px; width: auto;`;const last = clonedElement.getBoundingClientRect();

Now we need to apply styles to the element we are animating such that it will be in its “final” position (i.e. it should be on top of the add-to-cart icon). To determine where the element should be, we use the position of the flyTo element that was passed in through the trigger method. We then use the position values of that element, and apply them to the position of our cloned image element. Once the image element is in its final position, we use getBoundingClientRect() again to take a reading of the new position.

Invert

// Invertconst invert ={
      x: first.left - last.left,
      y: first.top - last.top,
      scaleX: first.width / last.width,
      scaleY: first.height / last.height,};