Recently, someone asked me if it is possible to create a shared element transition in an Ionic application. I wasn’t actually familiar with that specific term, but it is something I’ve wanted to try building in Ionic for a while and it’s actually a little bit easier than I thought it would be. The basic idea is that rather than just transitioning directly to a new page, we take one of the items on the existing page and animate that into its position on the new page.

This seems like it would be rather complicated to implement, but after seeing this video demonstrating the effect for an Android application, it highlighted that it’s really just a bit of an animation trick rather than having to have some kind of complicated navigation structure.

If you watch the video (and I recommend that you do), you will see that the basic idea behind creating this effect is:

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

There is no actual sharing of elements between the pages, we just make it look like there is by having the starting position of the “shared” element on the new page be the same as its position on the previous page.

We are going to create this process in an Ionic & Angular application using the ModalController and some simple animations. Ours won’t be quite as impressive as the one in the video as we will just be focusing solely on this concept of “sharing” the element between the two pages and animating it. The example in the video also has some additional animations playing on the initial page which we won’t be implementing (e.g. the items that weren’t chosen fly off the page). That’s not to say it can’t be done, in fact I imagine it wouldn’t require that much more effort, but perhaps that’s a tutorial for another time.

Here is what we will be creating by the end of this tutorial:

Keep in mind that whilst we will be building the example above, you should treat this blog post more as research or a proof of concept rather than a fully fleshed out method for creating shared element transitions in Ionic. The method I am using to achieve this is rather manual. You could still implement this in your own applications with a bit of tweaking, probably in a variety of different situations. However, I’d like to investigate a more reusable/adaptable way to go about this in future.

Before We Get Started

Last updated for Ionic 4.0.0

This is a somewhat advanced tutorial and will assume that you already have a reasonably strong understanding of Ionic and Angular. If you require more introductory level content on Ionic I would recommend checking out my book or the Ionic tutorials on my website.

1. Create the Basic Layout

We are going to implement a basic master/detail pattern for this tutorial. We will have a list of cards that display images on the master page, and then when one of these are clicked the image for that card will become the “shared” element that is animated into position on the detail page.

A lot of this is just going to be basic layout stuff, so let’s get that out of the way first. I’ll assume you already have a “home” and “detail” page set up.

Modify src/app/home/home.page.html to reflect the following:

<ion-header><ion-toolbarcolor="danger"><ion-title>
      Transition
    </ion-title></ion-toolbar></ion-header><ion-content><ion-card(click)="launchDetail($event)"*ngFor="let card of cards"><imgsrc="http://placehold.it/600x300"/></ion-card></ion-content>

We are just looping over an array of cards here which we will set up later, but notice that we are also sending the event information along with the (click) binding. This is important as it will allow us to determine the position of the element that was clicked.

Modify src/app/detail/detail.page.html to reflect the following:

<ion-header><ion-toolbarcolor="danger"><ion-title>Detail</ion-title><ion-buttonsslot="end"><ion-button(click)="close()"><ion-iconslot="icon-only"name="close"></ion-icon></ion-button></ion-buttons></ion-toolbar></ion-header><ion-content><img#headersrc="http://placehold.it/600x300"/><divclass="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>

Here we have set up a template that has a header image at the top (which will be the shared element we are animating). Since we don’t want padding for the header but we do want it for the content, we will set up a container class with its own padding.

Modify src/app/detail/detail.page.scss to reflect the following:

.container{padding: 20px;}

2. Create a Custom Modal 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.

If you are not already familiar with creating a custom modal animation in Ionic, I have a separate tutorial that you can view here: Create a Custom Modal Page Transition Animation in Ionic. It is not important for the sake of this tutorial that you understand the details of how this custom animation works if you are not interested.

Create a file at src/app/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(1000).beforeAddClass('show-modal').add(backdropAnimation).add(wrapperAnimation));}

We have created an animation that will animate to full opacity over one second.

3. Pass Position Information to the Modal

Now we need to define the launchDetail function so that we can launch the modal, but we also need to pass the information about the clicked element’s position to the modal page.

Modify src/app/home/home.page.ts to reflect the following:

import{ Component }from'@angular/core';import{ ModalController }from'@ionic/angular';import{ DetailPage }from'../detail/detail.page';import{ myFadeInAnimation }from'../animations/fade-in';

@Component({
  selector:'app-home',
  templateUrl:'home.page.html',
  styleUrls:['home.page.scss'],})exportclassHomePage{public cards =newArray(10);constructor(private modalCtrl: ModalController){}launchDetail(ev){this.modalCtrl.create({
      component: DetailPage,
      enterAnimation: myFadeInAnimation,
      componentProps:{'coords':{
          x: ev.target.x,
          y: ev.target.y
        }}}).then((modal)=>{
      modal.present();});}}

This is mostly just the normal method for launching a modal, but we are also suppying our custom enterAnimation and we pass in the coords of the clicked element using the componentProps of the modal.

4. Animate the Shared Elements Position

Now we just need to grab that passed in information and use it to animate the image element on the detail page from the position the element was in on the master page, to its normal position on the detail page.

Modify src/app/detail/detail.page.ts to reflect the following:

import{ Component, OnInit, ElementRef, Renderer2, ViewChild }from'@angular/core';import{ ModalController, NavParams }from'@ionic/angular';

@Component({
  selector:'app-detail',
  templateUrl:'./detail.page.html',
  styleUrls:['./detail.page.scss'],})exportclassDetailPageimplementsOnInit{

  @ViewChild('header') headerImage: ElementRef;constructor(private modalCtrl: ModalController,private navParams: NavParams,private renderer: Renderer2
  ){}ngOnInit(){let coords =this.navParams.get('coords');this.renderer.setStyle(this.headerImage.nativeElement,'transform',`translate3d(0, ${coords.y -56}px, 0) scale3d(0.9, 0.9, 1)`);this.renderer.setStyle(this.headerImage.nativeElement,'transition','0.5s ease-in-out');setTimeout(()=>{this.renderer.removeStyle(this.headerImage.nativeElement,'transform');},50);}close(){this.modalCtrl.dismiss();}}

We use @ViewChild to grab a reference to our image element so that we can animate it. In the ngOnInit function we grab the coords that were passed in to the modal using NavParams. We then set some initial styles on the image element. Using the coords information, we move the element to a position that matches the master page by using translate3d and we also scale it to be slightly smaller as it is on the master page.

When we change these styles back to their original styles, we want that transition to animate. So, we also modify the transition property of the element and give it a property of 0.5s ease-in-out which will animate the transition over half a second and use the ease-in-out animation easing.

After a slight delay, we then remove the transform style we applied which will trigger the animation. We should now have something like this:

Summary

I think there is more work to do here still, but we have a rather cool effect with relatively little effort. This isn’t just a “cool” animation either, it actually adds something to the user experience as it maintains the context better between the pages as it very clearly indicates that the new page contains information about the specific item that was clicked.

When we are building applications, there are many instances where we want data updates from the server to display immediately. Perhaps we have a chat application and we want to display new messages to a user, or maybe we’ve built a game that needs to display an update to the user as soon as something happens on the server.

The problem with a typical client/server set up is that we would trigger a request from the client to load some data from a server when the application loads and it would pull in the latest set of data - for the sake of an example, let’s say we would load in all of the current chat messages from the server. Once that initial load and request has been made, what happens when somebody else updates the data on the server (e.g. when someone adds a new chat message)? Nobody would know that a new chat message has been added except the person who added it, so we need some way to check the data on the server after the initial request for data.

We could, for example, set up some code in our client-side application to check (or “poll”) the server every 10 seconds. Every 10 seconds the application would make a request to the server for the latest chat data, and load any new messages. This is a viable solution, but it’s not ideal. This approach has two glaring flaws which are:

1. A lot of likely unnecessary requests are made to the server
2. There is a potentially long delay before the user will see the new data (which would be especially annoying in a chat application)

This brings me to the topic of today’s tutorial, there is a much better way to handle this situation…

Introducing Web Sockets

The WebSocket API allows for event-based two-way communication between a browser and a server. If we consider our initial example of “polling” a server every 10 seconds to get new data to be like calling somebody on the phone every 10 seconds for updates, then using web sockets instead would be like just calling them once and keeping the call open in the background so either party can communicate instantly whenever required.

When using Web Sockets, an event could be triggered as soon as a new chat message is added by anybody, and any clients listening will instantly be notified. This means that the chat message that was added would show up near instantaneously for the other users.

NestJS has support for web sockets built-in, which makes use of the popular socket.io package. This makes setting up communications using the WebSocket API in NestJS rather simple.

In this tutorial, we are going to build a simple live chat application using NestJS and Ionic/Angular. We will use our NestJS server to:

• Broadcast any chat messages to any listening clients
• Notify when a new client connects
• Notify when a client disconnects

The server will just be used to relay information, it will be the responsibility of the clients to display the information. When we are done, the application should look something like this:

Before We Get Started

This tutorial assumes that you are already familiar with the basics of NestJS (and Ionic/Angular if you are using that on the front-end). If you need more tutorials on NestJS in general, I have more NestJS tutorials available here.

Although we are using Ionic on the front-end for this tutorial, it doesn’t particularly matter. You could use any front-end you like, but we will be covering specifically how to use the ngx-socket-io package which makes it easier to use socket.io in Angular. If you are not using Angular, then you would need to implement socket.io in some other way in your application (the basics concepts remain the same).

1. Creating the NestJS Server

First, we are going to create our NestJS server. In order to use web sockets in your NestJS project, you will need to install the following package:

npm install --save @nestjs/websockets

With that package installed, we are going to create a new module called ChatModule which will handle our web socket communication.

Run the following command to create a new module called Chat:

nest g module chat

Once the module has been generated, we are going to create a new file to implement a @WebSocketGateway.

Create a file at src/chat/chat.gateway.ts and add the following:

import{ WebSocketGateway, WebSocketServer, SubscribeMessage, OnGatewayConnection, OnGatewayDisconnect }from'@nestjs/websockets';

@WebSocketGateway()exportclassChatGatewayimplementsOnGatewayConnection, OnGatewayDisconnect {

    @WebSocketServer() server;
    users: number =0;asynchandleConnection(){// A client has connectedthis.users++;// Notify connected clients of current usersthis.server.emit('users',this.users);}asynchandleDisconnect(){// A client has disconnectedthis.users--;// Notify connected clients of current usersthis.server.emit('users',this.users);}

    @SubscribeMessage('chat')asynconChat(client, message){
        client.broadcast.emit('chat', message);}}

This is basically everything we need to handle the communication for our application, so let’s break it down. First, we decorate our class with @WebSocketGateway which is what will allow us to make use of the socket.io functionality.

You will notice that this class also implements OnGatewayConnection and OnGatewayDisconnect. This isn’t strictly required, but since we want to keep track of clients connecting and disconnecting we implement the handleConnection() and handleDisconnect() hooks. These will be triggered every time a client connects or disconnects.

We set up a member variable called server that is decorated with @WebSocketServer which will give us access to the server instance. We can then use this to trigger events and send data to connected clients. We make use of this in our handleConnection and handleDisconnect hooks where we are incrementing or decrementing the total number of users, and then notifying any connected clients of the new number of users.

The @SubscribeMessage decorator is used to listening to incoming messages. If we want to send a chat event from our client to the server, then we need to decorate the function that will handle that event with @SubscribeMessage('chat'). This function (onChat in this case) has two parameters: the first (which we are calling client) will be a reference to the socket instance, and the second (which we are calling message) will be the data sent by the client.

Since we want all connected clients to know about this chat message when it is received, we trigger a broadcast to those clients with client.broadcast.emit('chat', message). Then, any clients listening for the chat event would receive this data instantly.

We are almost done with the server, but before our gateway will start listening we need to add it to the providers in our chat module.

Modify src/chat/chat.module.ts to reflect the following:

import{ Module }from'@nestjs/common';import{ ChatGateway }from'./chat.gateway';

@Module({
    providers:[ ChatGateway ]})exportclassChatModule{}

Remember, when testing you will need to make sure your server is running with:

npm run start

2. Creating the Client-Side Application

With the server complete, now we just need to set up some kind of front-end client to interact with it. As I mentioned, we will be creating an example using Ionic/Angular but you could use any front-end you like. You could even have multiple different front ends interacting with the same server.

Install the following package in your Ionic/Angular project:

npm install --save ngx-socket-io

This package just implements socket.io in an Angular friendly way. As well as installing it, we will also need to configure the package in our root module.

Make sure to configure the SocketIoModule as shown in the app.module.ts file below:

import{ NgModule }from'@angular/core';import{ BrowserModule }from'@angular/platform-browser';import{ RouteReuseStrategy }from'@angular/router';import{ IonicModule, IonicRouteStrategy }from'@ionic/angular';import{ SplashScreen }from'@ionic-native/splash-screen/ngx';import{ StatusBar }from'@ionic-native/status-bar/ngx';import{ AppComponent }from'./app.component';import{ AppRoutingModule }from'./app-routing.module';import{ SocketIoModule, SocketIoConfig }from'ngx-socket-io';const config: SocketIoConfig ={ url:'http://localhost:3000', options:{}};

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

We use a url of http://localhost:3000 as this is where our NestJS server is running. In a production environment, you would change this to the location of wherever your NestJS server is running. Now, we are going to focus on implementing a chat service to handle most of the logic, and afterward, we will create a simple interface to send and receive chats.

Run the following command to create a chat service:

ionic g service services/chat

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

import{ Injectable }from'@angular/core';import{ Socket }from'ngx-socket-io';

@Injectable({
  providedIn:'root'})exportclassChatService{constructor(private socket: Socket){}sendChat(message){this.socket.emit('chat', message);}receiveChat(){returnthis.socket.fromEvent('chat');}getUsers(){returnthis.socket.fromEvent('users');}}

Once again, there isn’t actually all that much code required to get this communication working. We inject Socket from the ngx-socket-io package to get a reference to the socket instance, and then we utilise that our three methods.

The sendChat function will allow us to send a message to the server. We call the emit method with a value of chat which means that it is going to trigger the function on the server decorated with @SubscribeMessage('chat'). The server will receive the message sent, and then rebroadcast that to any other clients listening.

Whilst the sendChat function handles sending data to the server, the other two methods handle receiving data from the server. The receiveChat method listens to the chat event, which means that every time this line is triggered on the server:

client.broadcast.emit('chat', message);

The receiveChat method will get that message data. Similarly, the getUsers method listens to the users event, and every time this line is triggered on the server:

this.server.emit('users',this.users);

The getUsers method will receive the total number of active users. With these methods in place, let’s make use of them in one of our pages.

Modify src/app/home/home.page.ts to reflect the following:

import{ Component, OnInit }from'@angular/core';import{ ChatService }from'../services/chat.service';

@Component({
  selector:'app-home',
  templateUrl:'home.page.html',
  styleUrls:['home.page.scss'],})exportclassHomePageimplementsOnInit{public users: number =0;public message: string ='';public messages: string[]=[];constructor(private chatService: ChatService){}ngOnInit(){this.chatService.receiveChat().subscribe((message: string)=>{this.messages.push(message);});this.chatService.getUsers().subscribe((users: number)=>{this.users = users;});}addChat(){this.messages.push(this.message);this.chatService.sendChat(this.message);this.message ='';}}

Your page might not look exactly like this, but the example above is the gist of what needs to happen. In our ngOnInit hook we subscribe to both the receiveChat and getUsers methods which both return an observable. Every time a communication is received from the server, the observable will emit the new data and we can do something with it. In this case, we are pushing any new messages into the messages array, and any time we receive the total number of users from the server we set the users member variable to that value.

The only other method we have here is addChat which simple passes on whatever message the user typed to the sendChat method in the chat service (as well as adding the message to the messages array, since this client won’t receive a broadcast for its own chat message).

All of the main functionality has been completed now, but let’s create a nice chat interface to test it out in.

Modify src/app/home/home.page.html to reflect the following:

<ion-headerno-border><ion-toolbarcolor="tertiary"><ion-title>Live Chat</ion-title></ion-toolbar></ion-header><ion-content><ion-card><ion-card-content>
        There are currently <strong>{{users}}</strong> users online. Start chatting!
    </ion-card-content></ion-card><ion-listlines="none"><ion-item*ngFor="let message of messages">
      {{message}}
		</ion-item></ion-list></ion-content><ion-footer><ion-toolbar><textareaspellcheck="true"autoComplete="true"autocorrect="true"rows="1"class="chat-input"[(ngModel)]="message"placeholder="type message..."(keyup.enter)="addChat()"></textarea><ion-buttonsslot="primary"><ion-button(click)="addChat()"slot="end"class="send-chat-button"><ion-iconslot="icon-only"name="send"></ion-icon></ion-button></ion-buttons></ion-toolbar></ion-footer>

Modify src/app/home/home.page.scss to reflect the following:

textarea {
    width:calc(100%-20px);
    margin-left:10px;
    background-color: #fff;
    font-size:1.2em;
    resize: none;
    border: none;}

3. Test with Multiple Clients

Now, all we need to do is test it in the browser! This is a little bit awkward because we are going to need multiple clients in order to test the web socket communication. How you achieve this might depend on what kind of front-end you are using, but if you are using Ionic/Angular it is simple enough.

First, make sure your NestJS server is running with:

npm run start

Next, in a separate terminal window, serve your Ionic application:

ionic serve

The, open up another terminal window, and serve your Ionic application again:

ionic serve

You should now have two instances of your Ionic application running on two separate ports in the browser. You should be able to enter a chat message into either instance, and it will immediately show up in the other. At this point, the application should look something like this:

Summary

This is a very simplistic/bare-bones example, but it demonstrates the basic usage of web sockets. In a more typical application, you might want to extend this to perhaps store the messages in a database like MongoDB - you could still use a similar set up where you broadcast new chat messages to the clients, but you would then also store the messages in the database.

If you’d like to dive further into using web sockets in NestJS, there is a great complex chat application example available here and you can also find a lot more information in the NestJS documentation for web sockets.

With a little bit of research, you will quickly discover that the Ionic Framework is a framework for building cross-platform applications using web technology. What might be less obvious is exactly what it is that Ionic provides, and what using Ionic might look like for you.

This is especially the case today. The current generation of Ionic has opened the door for Ionic to be used in a myriad of different circumstances and in conjunction with different frameworks. This is great in the way that it provides developers with even more opportunities, but it can also make the Ionic ecosystem a little more confusing for newcomers.

The goal of this article is to provide a concise breakdown of what Ionic is and the options you have for using it. I will be addressing each of the following questions:

• What exactly isIonic?
• How do you build Ionic applications?
• What is StencilJS and how does it relate to Ionic?
• What role do Angular, React, and Vue play in Ionic applications?
• What approach should you use when building Ionic applications?

NOTE: The current version of Ionic (4.x) takes a vastly different approach than previous iterations of the framework. Previous versions of the framework were built specifically to be used with the Angular framework, but now Ionic is a generic framework that can be used in conjunction with any framework (or without using a framework at all). This article will just be focusing on the current version of Ionic.

What is Ionic?

At its core, the Ionic framework is a set of web components. Web components allow developers to create their own custom elements that can be reused in any web application. Just as we have an <input> or <button> element that we can use by default with HTML, web components allow us to create custom elements like <my-timer> or <my-photo-viewer> that can be dropped in just like normal HTML.

In the case of Ionic, the set of web components that are provided to us to use in our applications look like this:

• <ion-list>
• <ion-item>
• <ion-button>
• <ion-header>
• <ion-card>

Each of the Ionic web components is prefixed with ion indicating that these are Ionic web components (as is the standard practice for creating web components). If we ignore the ion- prefix, we can see that these are examples of the following user interface (UI) components:

• List
• Item
• Button
• Header
• Card

The goal of the web components that Ionic provides is to supply us with all of the elements we would need to create a mobile application. This means we can easily implement common mobile patterns like scrolling lists, side menus, tabs and more just by dropping in some simple HTML syntax. There are many more components available than the ones I have listed here.

A typical page in an Ionic application might look like this:

<ion-header><ion-title>My Shopping List</ion-title></ion-header><ion-content><ion-list><ion-item>Bread</ion-item><ion-item>Iced Coffee</ion-item><ion-item>Pasty</ion-item></ion-list></ion-content>

With just a few web components, the example above will create a user interface that looks and behaves like a typical native mobile app page with a scrolling list.

The components that Ionic provide are also typically more complex than simple HTML elements. Web components allow us to build complex logic into the elements. Sometimes an Ionic component that we use might just provide some simple styling to match what you would expect to see in an iOS/Android application (like an <ion-button>) and sometimes the components will also have complex Javascript embedded into them (like the <ion-datetime> component that provides a mobile style scrolling date picker).

Although Ionic’s web components are specifically designed to work well on mobile devices, they can also be used in desktop applications.

Using Ionic

When building applications with Ionic, we don’t typically only use the web components that Ionic provides. We can’t really just drop these web components into an HTML file and build an entire application.

There is more to an application that just the user interface. We need to handle routing/navigation, data, logic, events, dynamic templates, and more. You could implement your own methods to achieve these aspects of your application just by using plain Javascript, but typically people will use an additional framework in conjunction with Ionic to handle these aspects of the application. We will discuss frameworks more in the next section.

As well as the web components themselves, Ionic also provides some additional tooling to help build applications.

Ionic CLI

The Ionic CLI (Command Line Interface) is a command line tool that is used to manage Ionic applications. It allows you to easily create an Ionic application, and provides tooling for serving your application throughout development, and building your application for production.

Capacitor

Capacitor is a separate project to Ionic (it is still created by the Ionic team), but it is used in conjunction with Ionic. Capacitor provides a common API for accessing native functionality across different platforms. This means that if you want to access functionality like the camera, you can use the same code for iOS and Android without having to worry about the underlying native implementation on each platform.

Capacitor also allows you to build your Ionic application as a native application for iOS/Android/Desktop. The Ionic CLI will allow you to create a build that can be deployed to the web, but to deploy to native devices you will need to use a solution like Capacitor.

Capacitor fulfills a similar role to the popular Cordova.

Appflow

Ionic Appflow is an optional platform (also provided by the Ionic team) that you can use in conjunction with your Ionic applications. This is a paid solution that provides functionality like continuous deployment and automatic application builds.

Ionic doesn’t just provide the user interface components for building mobile applications, they provide a start to finish development environment.

Angular, React, and Vue

As I mentioned, you don’t need to use an additional framework to build an application using Ionic’s web components, but most people do choose to use a framework to build applications today.

To put it simply, Ionic provides the user interface and the framework you are using with Ionic will provide the application logic. Since Ionic uses web components, there is no real limitation to what frameworks you can use - as long as the framework plays nicely with web components, you can use it.

Although you could use Ionic with other frameworks, Ionic also provides specific support for the three most popular Javascript application frameworks today: Angular, React, and Vue. You will find that as well as the set of web components Ionic supplies through the @ionic/core package, they also supply @ionic/angular, @ionic/react, and @ionic/vue packages. These packages just make it a little easier to use Ionic out of the box with these frameworks.

At the end of this article, I will provide my thoughts on which framework you should use when building Ionic applications. But first, there is one more piece of the puzzle we need to discuss.

The Role of StencilJS

StencilJS is the tool that the Ionic team uses to build their web components. StencilJS is a web component compiler, not a framework. In short, StencilJS just makes it easier to create web components. Although Stencil syntax is used to build the web components, the end result that is built is just a generic web component with nothing to do with Stencil - this is why it is a compiler and not a framework.

StencilJS is also available for you to use as well to build your own web components. It is in no way required that you use or understand Stencil in order to build Ionic applications, but it serves an interesting niche as a bit of a middle option between using a framework with Ionic and not using one.

Although StencilJS is not a framework, you can kind of use it as one to build Ionic applications. Ionic provides a StencilJS starter project called the Ionic PWA Toolkit which is mostly just a StencilJS application with the Ionic web components inlcuded by default and a basic project structure set up.

Instead of using a framework, we can use StencilJS to build out a bunch of web components that represent the various pages/components in our application. The toolkit then also provides some basic routing/navigation to switch between displaying those web components, and since we can handle the logic in the web components themselves, we kind of have this “pseudo-framework” that provides us with a lot of the functionality of a typical modern framework, without actually having to use one.

Personally, I think going this route is a little trickier than the other options currently, but there are some strong benefits to using StencilJS to build an Ionic application:

• StencilJS is not a framework, it just helps you build web components, so your resulting application does not need to include any framework libraries that will need to be loaded
• The work you put into building your application’s components is not tied to any specific framework, since they are just web components. You could reuse those components in other applications and other frameworks, and you never have to worry about the framework you decided to base your application on “falling out of favour”. It’s just generic web tech.

Which Option is Best?

Deciding on an approach to use in such a complex space can be hard, and this is one of those “it depends” kind of questions (isn’t it always?). Although there are no clear cut answers here, I will give my thoughts on which approach might suit you best.

• If you have a preference for Angular, React, or Vue use Ionic with the framework you are comfortable with. However, keep in mind that the @ionic/vue and @ionic/react packages are currently in alpha/beta.
• If you do not have a preference for a particular framework (but want to use one), use Angular. Since Ionic has historically used Angular, most of the community uses it, so there are far better resources/documentation/tutorials available. The @ionic/angular package is also stable/mature.
• If the concept of not using a framework appeals to you and you are reasonably comfortable with web development, use StencilJS. StencilJS is reasonably new so there are probably going to be some things you need to figure out for yourself, but there are some powerful benefits to using it.

If you’re still not sure which approach to use, I think Ionic/Angular is a good default, but it doesn’t matter too much. Just start learning and start getting experience and then you will have a better basis for determining which approach suits you best.

When building StencilJS applications (whether you are using Ionic with it or not) you will be using JSX to create the templates for your components. JSX is a syntax extension to standard ECMAScript (JavaScript) that adds additional XML style syntax. It was created by Facebook and popularised by its usage in the React framework, but JSX can be used outside of React - which is obviously the case for StencilJS.

In over-simplified terms, JSX allows you to mix HTML with JavaScript. If you’ve never used it, it’s definitely one of those kind of things that feels a little weird to get used to at first. The purpose of this article is to introduce you to the basics of JSX and how it would be used in StencilJS application, to help get you over that initial confusion hump.

Since many of the readers of this blog will already be familiar with Angular, I will make some references and comparisons to Angular throughout this article. However, if you are not familiar with Angular you will still be able to read the article (just ignore the references).

If you haven’t already been using something like React to build applications, then chances are you would be used to defining standard-looking HTML files to contain your template e.g:

my-template.html

<div><p>Hello</p></div>

Or if you were defining templates inside of your JavaScript/TypeScript files then you would typically define a template string like this:

template:`
  <div><p>Hello</p></div>
`

Either way, we are just using standard syntax in these cases. However, when you start using JSX, you will also be defining your templates inside of your JavaScript/TypeScript files but it will look something like this:

render(){return<div><p>Hello</p></div>;}

or this:

render(){return(<div><p>Hello</p></div>)}

and maybe you even have some variables defined with HTML syntax attached to them:

const myMessage =<p>Welcome to my app!</p>

If you’ve never used JSX then the examples above look like they would cause a bunch of syntax errors. We aren’t defining HTML inside of strings, we are just straight-up writing HTML inside of a JavaScript/TypeScript file. But, mixing HTML and JavaScript like this is exactly what JSX allows.

We are going to go through some examples that cover the basics of how to use JSX. Although this is in the context of a StencilJS application, the same concepts apply to JSX as a general concept.

A Basic Template

When building an application with StencilJS, we will have various components that make up our application. These components will each define a render function that specifies the template.

The render function simply needs to return the template, which will use JSX, that the component should use. This will look something like this:

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

@Component({
    tag:'app-profile',
    styleUrl:'app-profile.css'})exportclassAppProfile{render(){return(<div><p>Hello</p></div>)}}

The render function should return the JSX template, but it is also possible to add additional code inside of the render function (which could be utilised inside of the JSX template):

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

@Component({
    tag:'app-test',
    styleUrl:'app-test.css'})exportclassAppTest{const myMessage =<p>Welcome to my app!</p>;render(){return(<div><p>{myMessage}</p></div>)}}

Returning Multiple Root Nodes

The render function must return a single root node, that means that this is will work:

return(<div></div>)

and this will work:

return(<div><p>Hello</p><div><p>there.</p></div></div>)

but this will not:

return(<div>Root one</div><div>Root two</div>)

To address this scenario you can either wrap the two nodes inside of a single node:

return(<div><div>Root one</div><div>Root two</div></div>)

or you can return an array of nodes like this:

return([<div>Root one</div>,<div>Root two</div>])

Notice the use of square brackets to create an array, and that each node is followed by a comma as in an array. Although it may look a little strange to use HTML syntax in an array like this, it is the same idea as doing this:

return['array element 1','array relement 2']

Expressions

Expressions allow us to do things like execute logic inside of our templates or render out a variable to display on the screen. If you are coming from an Angular background, the idea is basically the same as interpolations with double curly braces, except that we just use a single curly brace like this:

render(){return(<div><p>{1+1}</p></div>)}

This example would execute the 1 + 1 operation, and display the result inside of the paragraph tag. In this case, it would therefore render the following out to the DOM:

<div><p>2</p></div>

We could also use expressions to make function calls:

calculateAddition(one, two){return one + two;}render(){return(<div><p>{this.calculateAddition(1,5)}</p></div>)}

Render out local or class member variables:

public myNumber: number =1;render(){const message =<p>Hi</p>;return(<div><p>{message}</p><p>{this.myNumber}</p></div>)}

and much more, some of which we will touch on later. A difference you might notice here if you are coming from an Angular background is that inside of the curly braces we need to reference the this scope in order to access the member variable, which isn’t the case with Angular templates.

Styles

If you attempt to add a style to an element in JSX like this:

    render(){
        return (
            <divstyle="background-color: #f6f6f6;padding: 20px;"><p>Hello</p></div>
        )
    }

You will be met with an error that reads something like this:

Type 'string' is not assignable to type '{ [key: string]: string; }'.

But what’s the deal with that? Aren’t we allowed to use HTML syntax? Not quite, there are a few differences. With JSX, inline styles must be supplied as an object, where the properties of that object define the styles you want:

render(){return(<div style={{
          backgroundColor:`#f6f6f6`,
          padding:`20px`}}><p>Hello</p></div>)}

We are assigning an expression (which we just discussed) to style that contains an object representing our style properties. You will notice that we are using camelCase - so instead of using the usual hyphenated properties like background-color or list-style-type we would use backgroundColor and listStyleType.

Conditional Templates

There are different ways to achieve conditionally displaying data/elements with JSX, so let’s take a look at a few. We covered before how you could make a function call inside of an expression in your template, and that is one way that you could conditionally display an element:

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

@Component({
    tag:'app-test',
    styleUrl:'app-test.css'})exportclassAppTest{private loggedIn: boolean =false;getWelcomeMessage(){if(this.loggedIn){return'Welcome back!';}else{return'Please log in';}}render(){return(<div><p>{this.getWelcomeMessage()}</p></div>)}}

You could also achieve the same effect by building some logic directly into the expression in the template, rather than having a separate function:

render(){return(<div><p>{this.loggedIn ?'Welcome back!':'Please log in.'}</p></div>)}

You could render entirely different chunks of your template using if/else statements:

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

@Component({
    tag:'app-test',
    styleUrl:'app-test.css'})exportclassAppTest{private loggedIn: boolean =false;render(){if(this.loggedIn){return(<div><p>Welcome back!</p></div>)}else{return(<div><p>Please log in.</p></div>)}}}

You can completely remove any rendering to the DOM by returning null instead of an element:

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

@Component({
    tag:'app-test',
    styleUrl:'app-test.css'})exportclassAppTest{private loggedIn: boolean =false;render(){if(this.loggedIn){return(<div><p>Welcome back!</p></div>)}else{returnnull}}}

If you don’t want to return entirely different templates depending on some condition (this could get messy in some cases) you could also render entirely different chunks just by using a ternary operator inside of your template like this:

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

@Component({
    tag:'app-test',
    styleUrl:'app-test.css'})exportclassAppTest{private loggedIn: boolean =false;render(){return(<div>{this.loggedIn

	    			?<div><h2>Hello</h2><p>This is a message</p></div>:<div><h2>Hello</h2><p>This is a different message</p></div>}</div>)}}

If you aren’t familiar with the ternary operator, we are basically just looking at this:

this.loggedIn ?'logged in':'not logged in';

which is a simplified version of:

if(this.loggedIn){return'logged in';}else{return'not logged in';}

We can also simplify the ternary operator more if we don’t care about the else case. For example, if we only wanted to show a message to a user who was logged in, but we didn’t care about showing anything to a user who isn’t, we could use this syntax:

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

@Component({
    tag:'app-test',
    styleUrl:'app-test.css'})exportclassAppTest{private loggedIn: boolean =true;render(){return(<div>{this.loggedIn &&<div><h2>Hello</h2><p>This is a message</p></div>}</div>)}}

This will only render out the message if loggedIn is true. The methods I have mentioned here should be enough to cover most circumstances, but there are still even more you can use. It’s a good idea to have a bit of a search around and see what kinds of methods suit you best.

Looping over Data

We will often want to create templates dynamically based on some array of data like an array of todos or posts and so on. In Angular, this is where you would use an *ngFor structural directive to loop over that data. However, with StencilJS and JSX we once again just use standard JavaScript syntax/logic embedded directly into the template.

We can use the map method on an array of data to loop through the data and render out a part of the template for each iteration. Let’s take a look at an example from the documentation:

render(){return(<div>{this.todos.map((todo)=><div><div>{todo.taskName}</div><div>{todo.isCompleted}</div></div>)}</div>)}

In this example, we would have a class member named todos that we are looping over. For each todo we will render this out to the DOM:

<div><div>{todo.taskName}</div><div>{todo.isCompleted}</div></div>

The {todo.taskName} and {todo.isCompleted} expressions used here will be executed and the values for the paticular todo in that iteration of the map method will be used.

In order for StencilJS to be able to perform as efficiently as possible, it is important that if you intend to change this data (e.g. you can add/remove todos) that you give each todo that is rendered out a unique key property. You can attach that key to the root node of whatever you are rendering out for each iteration, e.g:

render(){return(<div>{this.todos.map((todo)=><div key={todo.id}><div>{todo.taskName}</div><div>{todo.isCompleted}</div></div>)}</div>)}

Event Binding

The last thing we are going to cover is event binding, which we will use mostly to handle users clicking on buttons or other elements. We can handle DOM events by binding to properties like onClick. For example, if we wanted to run a method that we created called handleClick() when the user clicks a button we might do something like this:

<ion-button onClick={this.handleClick(event)}>Click me</ion-button>

This is fine, and would invoke our handleClick method, but the downside of this approach is that it won’t maintain the scope of this. That means that if you were to try to reference a member variable like this.loggedIn inside of your handleClick method it wouldn’t work.

You can solve this issue in either of the following ways. You could manually bind the function to the correct scope like this:

<ion-button onClick={this.handleClick(event).bind(this)}>Click me</ion-button>

or you could use an arrow function like this (which is the more popular approach):

<ion-button onClick={(event)=>this.handleClick(event)}>Click me</ion-button>

As well as onClick you can also bind to other DOM events like onChange and onSubmit. If you are using Ionic, then you could also bind to any of the events that the Ionic web components emit.

Summary

As always, there is still much to learn. However, the concepts we have covered in this article should be enough to get you started with JSX and get you used to the initial oddities of using JSX.

For further learning, I would recommend reading the JSX section in the StencilJS documentation as well as the React documentation for JSX. Not all of the React documentation will apply to StencilJS, but it is a good way to gain a broader understanding of JSX in general.

A StencilJS application, like many modern applications including those built with Angular or React, consists of a “tree” of components (in the case of StencilJS, this is a tree of web components).

We start with our root component that is added to the index.html file (the entry point for the application), then our root component will add additional components to its template, and then those components will add additional components to their templates and so on.

If we were to visualise the structure of a typical Ionic application built with StencilJS it might look something like this:

<app-root><ion-app><ion-router></ion-router><ion-nav><app-home><my-custom-component></my-custom-component></app-home></ion-nav></ion-app></app-root>

The “root” of our tree is <app-root> which then branches out to <ion-app> which branches out to <ion-router> and <ion-nav> and then our <ion-nav> branches out to <app-home> and so on. The entire application is encapsulated/nested within our initial <app-root> component, which you could consider to be the base of a tree.

Understanding this structure is key to understanding the concepts we will be discussing in this article. Before we discuss exactly what Stencil’s State Tunnel is (and how to use it), we are going to cover the basics of passing data through a StencilJS application. This will help highlight how using state management can simplify that process.

Throughout the article we will also be making references to React’s Context API and Redux - if you are already familiar with these concepts then you will have a headstart in understanding State Tunnel.

Passing Data to Components

If we want to pass data to a component, we can do so using props. If we have the following structure:

<component-one><component-two></component-two></component-one>

If we want to pass data from component-one to component-two we can do so using a prop like this:

<component-one><component-twoname="Josh"></component-two></component-one>

We could then retrieve that data inside of component-two.tsx using the @Prop decorator:

@Prop() name: string;

This concept can be used to pass data throughout an application, even to deeply nested child components. For example, let’s take a look at an example using an Ionic web component structure:

<app-root><app-home><some-custom-component></some-custom-component></app-home><app-profile></app-profile></app-root>

If we want to share some data from app-root among both the app-profile and some-custom component components (e.g. we are attempting to create some kind of “global” data) we could do so by using props like this:

<app-root><app-home userData={data}><some-custom-component userData={data}/></app-home><app-profile userData={data}/></app-root>

This concept is referred to as prop drilling. We basically pass the data to the component that needs it by “drilling” through each level of nesting with props. To get data from app-root to some-custom-component we first pass it to app-home and then app-home can pass it to some-custom-component.

There is nothing wrong with doing this, but you can see how cumbersome it could become if you have a high level of nesting. If you wanted to pass some data to a component that was nested 6 levels deep, you need to do a lot of “drilling”.

There are other methods for achieving the data sharing we are aiming to accomplish, but in this article, we are going to focus on something that StencilJS offers us out of the box.

Introducing Stencil State Tunnel

StencilJS provides a package called State Tunnel that allows us to share “state” throughout the application. By “state” we mostly just mean “data”. If our application has various dynamic parts that can be changed (e.g. different users might log in, different settings or filters might be applied) then our application’s “state” can change, and parts of our application might want to know what that “state” is.

Instead of having to pass data through each component along the way with prop drilling, with State Tunnel we can kind of teleport or “tunnel” data from one component to another. We could pass data directly from app-root to any component, no matter how many levels of nesting we have, by using State Tunnel.

If you are familiar with React’s Context API, State Tunnel is heavily inspired by that and the general concepts are largely the same.

Basically, we can change this:

to this:

If you have an Angular background, you could consider this to somewhat fill the role of providers/services - where in Angular we can “inject” a service into particular components to provide values and methods. As we will touch on later, Redux might be a better fit for this role but State Tunnel can be used to achieve it too.

Using Stencil State Tunnel

Now we are going to walk through the basics of using State Tunnel in a StencilJS application. Before we begin, you will need to make sure that you have the following package installed in your StencilJS project:

npm install --save @stencil/state-tunnel

1. Create the Tunnel

We can create a “tunnel” by implementing a file that makes use of the createProviderConsumer provided by the @stencil/state-tunnel package. We create an interface containing the data or methods that we want to be able to pass through the application:

Create a file at src/components/data/user.tsx and add the following:

import{ createProviderConsumer }from"@stencil/state-tunnel";exportinterfaceState{
  username: string;}exportdefault createProviderConsumer<State>({
    username:null},(subscribe, child)=>(<context-consumer subscribe={subscribe} renderer={child}/>));

The first parameter we supply to the createProviderConsumer here just sets a default value for the data that we are passing, and the second argument will generally remain the same for any tunnel you create.

2. Pass State to the Tunnel

Next, we need to add our tunnel to the root component and pass it the appropriate “state”. You do not need to set this up on the root component, but since the root component contains all other components, by setting up the tunnel on the root component you will be able to access the data from the tunnel anywhere in the application.

Modify src/components/app-root/app-root.tsx to include your tunnel:

import{ Component }from"@stencil/core";import Tunnel from"../data/user";

@Component({
  tag:"app-root",
  styleUrl:"app-root.css"})exportclassAppRoot{render(){const state ={
      username:"Josh"};return(<ion-app><ion-router useHash={false}><ion-route url="/" component="app-home"/><ion-route url="/profile/:name" component="app-profile"/></ion-router><Tunnel.Provider state={state}><ion-nav /></Tunnel.Provider></ion-app>);}}

The important part here is that any child of <Tunnel.Provider>, at any level of nesting, will be able to access data/methods from the tunnel. In the case of an Ionic application, all of the components in the application are displayed using <ion-nav />, so by surrounding <ion-nav /> with our tunnel we will be able to access the data all throughout the application.

3. Consume State from the Tunnel

Now we just need to access the data from the tunnel, and there are actually a couple of ways to do this. I will show you my preferred method of using injectProps, although it’s not really the “default” approach. I find that this approach is a little cleaner and it also allows for access to the data outside of the render method. You can read about the other approach in the documentation.

Add the tunnel to the component you want to access the data in:

import{ Component, Prop, Element }from'@stencil/core'import Tunnel from'../data/user'

@Component({
  tag:'app-profile',
  styleUrl:'app-profile.css',})exportclassAppProfile{

  @Element() el: AppProfile
  @Prop() username: string

  render(){return[<ion-header><ion-toolbar color="primary"><ion-buttons slot="start"><ion-back-button defaultHref="/"/></ion-buttons><ion-title>Profile</ion-title></ion-toolbar></ion-header>,<ion-content padding><p>My username is {this.username}</p></ion-content>,]}}

Tunnel.injectProps(AppProfile,['username'])

There are a couple of important parts here. First, it is important that we set up both @Element() and a @Prop():

  @Element() el: AppProfile
  @Prop() username: string

The injectProps method requires that the component has an @Element decorator (otherwise it can’t inject the prop), and then we use the @Prop to hold the data that is being passed in through the tunnel.

At the bottom of the file, we add this line:

Tunnel.injectProps(AppProfile,['username'])

To pull the data in from the tunnel and set it up on our @Prop.

What about Redux?

If you are familiar with Redux, then you will probably notice similarities with what we are trying to achieve here and Redux. In a sense, Redux is a more complex/powerful/capable version of the React Context API, and the same comparison applies to Stencil’s State Tunnel. For typical application purposes, you might find Redux a better fit for state management, and StencilJS also provides Stencil Redux for this purpose.

I will likely be covering Redux in more depth in future posts.

Summary

Stencil State Tunnel is a convenient way to share state among various components - all you need to do is install the package, create a tunnel and add it the root component (or to the some parent/ancestor of the component you want to share to), and then consume that tunnel in whatever component you like (as long as it is a child of the tunnel entry point).

As I just mentioned, for general “application” purposes, you may find that Redux is a better fit (but that doesn’t mean you can’t still use State Tunnel for simple scenarios).

In this tutorial, we are going to tackle the basics of using NgRx for state management in an Ionic/Angular application.

If you are unfamiliar with the general concept of State Management/Redux/NgRx I would recommend watching this video: What is Redux? as a bit of a primer. The video is centered around Redux, but since NgRx is inspired by Redux the concepts are mostly the same. NgRx is basically an Angular version of Redux that makes use of RxJS and our good friends observables.

To quickly recap the main points in the Redux video, we might want to use a state management solution like NgRx/Redux because:

• It provides a single source of truth for the state of your application
• It behaves predictably since we only create new state through explicitly defined actions
• Given the structured and centralised nature of managing state, it also creates an environment that is easier to debug

and the general concept behind these state management solutions is to:

• Have a single source of “state” that is read-only
• Create actions that describe some intent to change that state (e.g. adding a new note, or deleting a note)
• Create reducers that take the current state and an action, and create a new state based on that (e.g. combining the current state with an action to add a new note, would return a new state that includes the new note)

To demonstrate using some pseudocode (I am just trying to highlight the basic concept here, not how you would actually do this with NgRx), we might have some “state” that looks like this:

{
    notes:[{title:'hello'},{title:'there'}],
    order:'alphabetical',
    nightMode:false}

The data above would be our state/store that contains all of the “state” for our application. The user might want to toggle nightMode at some point, or add new notes, or change the sort order, so we would create actions to do that:

ToggleNightMode
CreateNote
DeleteNote
ChangeOrder

An action by itself just describes intent. To actually do something with those actions we might use a reducer that looks something like this:

functionreducer(state, action){switch(action){case ToggleNightMode:{return{// New state with night mode toggled}}default:{return// State with no changes}}}

NOTE: This is just pseudocode, do not attempt to use this in your application.

This reducer function takes in the current state, and the action, and in the case of the ToggleNightMode action being supplied it will return a new state with the nightMode property toggled.

Before We Get Started

We will be taking a look at converting a typical Ionic/Angular application to use NgRx for state management. To do that, we are going to take the application built in this tutorial: Building a Notepad Application from Scratch with Ionic and add NgRx to it. You don’t need to complete that tutorial first, but if you want to follow along step-by-step with this tutorial you should have a copy of it on your computer.

We are going to keep this as bare bones as possible and just get a basic implementation up and running - mostly we will be focusing on the ability to create notes and delete notes. My main goal with this tutorial is to help give an understanding of the basic ideas behind NgRx, and what it looks like.

There is so much you can achieve with NgRx, and you can create some very advanced/powerful implementations, but that does come with an associated level of complexity. Looking at implementations of NgRx can be quite intimidating, so I’ve tried to keep this example as basic as possible (whilst still adhering to a good general structure). In the future, we will cover more complex implementations - if there is something, in particular, you would like to see covered, let me know in the comments.

Finally, it is worth keeping in mind that solutions like NgRx and Redux are not always necessary. NgRx and Redux are both very popular (for good reason), but they are not a “standard” that everyone needs to be using in all applications. Simple applications might not necessarily realise much of a benefit through using this approach.

1. Installing NgRx

We can easily install NgRx in an existing Angular application through the ng add command:

ng add @ngrx/store

As well as installing the @ngrx/store package it will also create a reducers folder with an index.ts file that looks like this:

import{
  ActionReducer,
  ActionReducerMap,
  createFeatureSelector,
  createSelector,
  MetaReducer
}from'@ngrx/store';import{ environment }from'../../environments/environment';exportinterfaceState{}exportconst reducers: ActionReducerMap<State>={};exportconst metaReducers: MetaReducer<State>[]=!environment.production ?[]:[];

We will be adding onto this implementation throughout the tutorial, but we’re mostly just going to leave it alone for now.

One thing in particular that we haven’t covered yet, but you may notice here, is the concept of a “meta reducer”. A regular reducer is responsible for taking in the state and an action and returning a new state. A meta reducer would take in a reducer as an argument and return a new reducer (kind of like how we can pipe operators onto an observable and return an altered observable if you are familiar with that concept). We won’t be using this concept in this tutorial, but you could use a meta reducer to do things like create a logging service for debugging (e.g. create a meta reducer that logs out some value every time the ToggleNightMode action is triggered).

The ng add command also adds the following line to your app.module.ts file:

StoreModule.forRoot(reducers,{ metaReducers })

This takes a global approach to implementing state management, but if you prefer you can also use StoreModule.forFeature in your individual lazy loaded modules to help keep things separate. There are many approaches you could take to structuring NgRx in your application. As I mentioned, I am trying to keep things simple here, so I would recommend taking a look at a few examples to see what style suits you best.

We are also going to store our actions in an actions folder, but the command doesn’t create that for us automatically. Let’s do that now.

Create an actions folder and note.actions.ts file at src/app/actions/note.actions.ts

Let’s start looking into how we can implement our first action.

2. Creating the Actions

To create an action we create classes that implement Action from the NgRx library. As we discussed, an action just describes intent. We won’t be adding any code to actually do anything here, we just want to describe what we want to do.

Modify src/app/actions/note.actions.ts to reflect the following:

import{ Action }from"@ngrx/store";import{ Note }from"../interfaces/note";exportenum ActionTypes {
  CreateNote ="[Notes Service] Create note",
  DeleteNote ="[Notes Service] Delete note"}exportclassCreateNoteimplementsAction{
  readonly type = ActionTypes.CreateNote;constructor(public payload:{ note: Note }){}}exportclassDeleteNoteimplementsAction{
  readonly type = ActionTypes.DeleteNote;constructor(public payload:{ note: Note }){}}export type ActionsUnion = CreateNote | DeleteNote;

First, we have an ActionTypes enumerated type that lists our various actions related to notes, and a description of what the action will do. Since these actions will be triggered from our existing notes service (you can trigger these actions elsewhere if you like) we make a note of the source of the action in the square brackets. This is purely to be more explicit/descriptive, it doesn’t serve a functional purpose.

We then create classes for each of the actions. It implements Action, it defines a type so we can tell what kind of action it is, and we can optionally supply a payload for that action. In the case of creating and deleting notes we will need to send a payload of data to correctly add or delete a note, but some actions (like toggling nightMode) would not require a payload.

Finally, we have the ActionsUnion which exports every action created in this file.

3. Creating the Reducers

As we now know, actions don’t do anything by themselves. This is where our reducers come in. They will take the current state, and an action, and give us a new state. Let’s implement our first reducer now.

Create a file at src/app/reducers/note.reducer.ts and add the following:

import*as fromNote from"../actions/note.actions";import{ Note }from"../interfaces/note";exportinterfaceNoteState{
  data: Note[];}exportconst initialState: NoteState ={
  data:[]};exportfunctionreducer(
  state = initialState,
  action: fromNote.ActionsUnion
): NoteState {switch(action.type){case fromNote.ActionTypes.CreateNote:{return{...state,
        data:[...state.data, action.payload.note]};}case fromNote.ActionTypes.DeleteNote:{return{...state,...state.data.splice(state.data.indexOf(action.payload.note),1)};}default:{return state;}}}

Things are starting to look a little bit more complex now, so let’s break it down. There is some stuff we are going to need in our reducer from our note actions that we just created, so we import everything from that actions file as fromNote so that we can make use of it here (this saves us from having to import everything that we want to use from that file individually).

We define the structure or “shape” of our note state as well as supply it with an initial state:

exportinterfaceNoteState{
  data: Note[];}exportconst initialState: NoteState ={
  data:[]};

The only data we are interested in are the notes themselves which will be contained under data, but we could also add additional state related to notes here if we wanted (like sort order, for example).

The last bit is the reducer function itself:

exportfunctionreducer(
  state = initialState,
  action: fromNote.ActionsUnion
): NoteState {switch(action.type){case fromNote.ActionTypes.CreateNote:{return{...state,
        data:[...state.data, action.payload.note]};}case fromNote.ActionTypes.DeleteNote:{return{...state,...state.data.splice(state.data.indexOf(action.payload.note),1)};}default:{return state;}}}

As you can see, the arguments for the reducer function are the state and the specific action which needs to be one of all the possible note related actions which we defined in our actions file. All we are doing here is switching between the possible actions, and we handle each action differently. Although we might run different code, the goal is the same: to return the new state that we want as a result of the action.

In the case of the CreateNote action, we want to return all of the existing state, but we also want the data to contain our new note (as well as all of the existing notes). We use the spread operator ... to return a new state object containing all of the same properties and data as the existing state, except by specifying an additional data property we can overwrite the data property in the new state. To simplify that statement a bit, this:

return{...state
      };

Basically means “take all of the properties out of the state object and add them to this object”. In effect, it is the same as just doing this:

return state;

Except that we are creating a new object. This:

return{...state,
        data:[...state.data, action.payload.note]};

Basically means “take all of the properties out of the state object and add them to this object, except replace the data property with this new data instead”. We keep everything from the existing state, except we overwrite the data property. We do still want all of the existing notes to be in the array in addition to the new one, so we again use the spread operator (this time just on the data) to unpack all of the existing notes into a new array, and then add our new one.

To reiterate, this:

[...state.data]

would mean “create a new array and add all of the elements contained in the data array to this array” which, in effect, is the same as just using state.data directly (except that we are creating a new array with those same value). This:

[...state.data, action.payload.note]

means “create a new array and add all of the elements contained in the data array to this array, and then add action.payload.note as another element in the array. To simplify even further, let’s pretend that we are just dealing with numbers here. If state.data was the array [1, 2, 3], and action.payload.note was the number 7, then the code above would create this array:

[1,2,3,7]

Hopefully that all makes sense. Once again, the role of our reducer is to modify our existing state in whatever way we want (based on the action it receives) and then return that as the new state.

Before we can make use of our actions/reducers, we need to set them up in our index.ts file.

Modify src/app/reducers/index.ts to reflect the following:

import{
  ActionReducer,
  ActionReducerMap,
  createFeatureSelector,
  createSelector,
  MetaReducer
}from"@ngrx/store";import{ environment }from"../../environments/environment";import*as fromNote from"./note.reducer";exportinterfaceAppState{
  notes: fromNote.NoteState;}exportconst reducers: ActionReducerMap<AppState>={
  notes: fromNote.reducer
};exportconst metaReducers: MetaReducer<AppState>[]=!environment.production
  ?[]:[];

The important part that has changed here is:

import*as fromNote from"./note.reducer";exportinterfaceAppState{
  notes: fromNote.NoteState;}exportconst reducers: ActionReducerMap<AppState>={
  notes: fromNote.reducer
};

We set up our overall application state on the AppState interface (this is named State by default). We are just working with a single notes reducer here, but you could also have additional state, for example:

exportinterfaceAppState{
  notes: fromNote.NoteState;
  photos: fromPhoto.PhotoState;}

Our store or “single source of truth” creates a nested/tree structure that might look something like this:

{
    notes: [
        {title: 'hello'},
        {title: 'there'}
    ],
    photos: [
        {url: ''},
        {url: ''}
    ]
}

When we are creating our notes actions/reducers we are just working within the notes“sub-tree” but it is still a part of the entire application state tree.

We also add the reducer we created for our notes under the notes property in the reducers constant that is exported (and is in turn used in our app.module.ts by StoreModule.forRoot()).

4. Creating Selectors

The last thing we are going to do before making use of our new state management solution in our notes service is create some selectors. A selector will allow us to read state from our store.

To create a selector, we can use createSelector which is provided by NgRx. We just supply it with the state we want to select from (e.g. the “sub-tree” of our state that we want to access), and a function that returns the specific data that we are interested in.

Add the following to the bottom of src/app/reducers/note.reducer.ts:

exportconstgetNotes=(state: NoteState)=> state.data;exportconstgetNoteById=(state: NoteState, props:{ id: string })=>
  state.data.find(note => note.id === props.id);

We are creating two functions here to use with createSelector. The getNotes function, when given the notes from our state tree, will return just the data property (which is the one we are interested in, since it is what actually contains the notes data).

The getNoteById function will take in additional props that can be supplied when attempting to select something from the store, which will allow us to provide an id. This function will then look for a specific note in the data that matches that id and return just that note.

Add the following to the bottom of src/app/reducers/index.ts:

exportconstgetNoteState=(state: AppState)=> state.notes;exportconst getAllNotes =createSelector(
  getNoteState,
  fromNote.getNotes
);exportconst getNoteById =createSelector(
  getNoteState,
  fromNote.getNoteById
);

With our functions created, we now just need to use them to create our selectors with createSelector. We first create a function called getNoteState to return the notes portion of our state tree. We then supply that, and the functions we just created, as arguments to createSelector in order to create our selector functions.

5. Accessing State and Dispatching Actions

Now everything finally comes together, and maybe you can see some of the benefit of doing all of this leg work up front. With our selectors created, we can easily get the data we want from our store wherever we like in our application. We can also easily make use of our CreateNote and DeleteNote actions.

To finish things off, we are going to keep the existing structure of the notes application, and just modify the methods in the NotesService.

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

import{ Injectable }from"@angular/core";import{ Store }from"@ngrx/store";import{ Storage }from"@ionic/storage";import{ Observable }from"rxjs";import{ Note }from"../interfaces/note";import*as NoteActions from"../actions/note.actions";import{ AppState, getAllNotes, getNoteById }from"../reducers";

@Injectable({
  providedIn:"root"})exportclassNotesService{public notes: Observable<Note[]>;constructor(private storage: Storage,private store: Store<AppState>){this.notes =this.store.select(getAllNotes);}getNote(id: string): Observable<Note>{returnthis.store.select(getNoteById,{
      id: id
    });}createNote(title):void{let id = Math.random().toString(36).substring(7);let note ={
      id: id.toString(),
      title: title,
      content:""};this.store.dispatch(newNoteActions.CreateNote({ note: note }));}deleteNote(note):void{this.store.dispatch(newNoteActions.DeleteNote({ note: note }));}}

To get access to our notes data, we just call this.store.select(getAllNotes) using the selector we created and it will return an observable. This observable will update any time the data in the store changes.

To get a specific note, we use our getNoteById selector, but since that selector also uses additional props (an id in this case) we pass that data along too:

returnthis.store.select(getNoteById,{
      id: id
    });

This will allow us to grab a specific note. Then we just have our createNote and deleteNote methods which are able to create or delete notes just be triggering the appropriate action and passing the note along with it:

this.store.dispatch(newNoteActions.CreateNote({ note: note }));this.store.dispatch(newNoteActions.DeleteNote({ note: note }));

Since we now have our notes class member set up as an observable now, if we want to be able to display the data it contains in our template we will need to add the async pipe.

Modify the <ion-item> in src/app/home/home.page.html to use the async pipe:

<ion-itembuttondetail*ngFor="let note of (notesService.notes | async)"[routerLink]="'/notes/' + note.id"routerDirection="forward">

The ngOnInit in the detail page will also need to be updated to make use of the observable returned by the getNote method now (if you have been following along with the notes application tutorial):

Modify ngOnInit in src/app/detail/detail.page.ts to reflect the following:

ngOnInit(){let noteId =this.route.snapshot.paramMap.get("id");this.notesService.getNote(noteId).subscribe(note =>{this.note = note;});}

Summary

Using NgRx looks a lot more complicated than just simply managing state yourself (and it is), but like a lot of things worth doing it’s a bit more upfront work for a longer-term payoff.

The state in this example application could rather easily be managed without using an advanced state management solution like NgRx. However, as applications become more complex the upfront work in setting up NgRx can be a great investment.

I decided to write this article in response to some common questions/statements/responses I’ve been seeing for quite a while. In discussions where the cross-platform capabilities of Ionic are being explained, it would be common for the Ionic team, or bloggers/educators like myself, to say that Ionic allows you to build the following applications from a single codebase:

• Web/PWA
• Native iOS
• Native Android
• etc.

It seems to be a point of contention to refer to an Ionic application as native even when the end result is a standard native .apk or .ipa file and it has the ability to use Native APIs, on the grounds that the user interface is displayed using an embedded web view and not Native UI controls.

Although I am of the opinion that it makes sense and avoids confusion among newer mobile developers to refer to Ionic applications as native when they are deployed to iOS/Android using an .ipa or .apk package (except in circumstances where the discussion is specifically about Web Views vs Native UI) - I am not here to convince you of that in this article, and I don’t think people who don’t share my view on this are wrong.

The point I do want to address is that inevitably when Ionic applications are referred to as native in any way, people will often make statements like (either out of genuine curiosity or feigned confusion for the point of snark):

“Oh, did Ionic finally get rid of web views?”

Whether the commenters are well-intentioned or not, there does seem to be a perception that web views are inherently a bad thing. The reliance on web views - an embedded browser to run/display web code - to display the user interface of an Ionic application in an iOS/Android environment is a limiting factor when compared to using Native UI. However, whilst there are disadvantages to using a web view, the usage of web views is fundamental to the underlying ideology of the Ionic framework and it provides some of Ionic’s biggest advantages.

If the Ionic framework were ever to “get rid of web views” then it would cease to be the framework we know and love that utilises the power of the web. In this article, I want to discuss some of the advantages that using web views provides.

A Disclaimer

I’m always cautious about writing these kinds of articles because I don’t want to contribute to the overall noise and unproductive arguments of framework wars.

It is my opinion that different tools are suited to different tasks, teams, and developers. I think people should use the tool or tools that work for them and try not to mix their identity and self-worth into the tools they are using. In most cases, I think there are far bigger concerns that determine the success of an application than whether you use Ionic, React Native, Flutter, Objective-C/Swift, Java/Kotlin, or something else to build the application.

I want to make it clear that the point of this article is not to make the point that:

“Web views are the best, and Native UI can go suck a lemon”

I am not making the point that the web view approach Ionic uses is better, just that it has worthwhile advantages and “uses web views” is not something you can just lump entirely in the “cons” column when weighing the pros/cons of what approach to use.

What is a web view?

Before discussing some of the advantages of web views, let’s quickly recap what exactly they are and what role it plays in an Ionic application. We will specifically consider the case of an iOS application, but the same concept applies to Android (and other platforms) as well.

If you were building a native iOS application in the “standard” way, you would be writing your application entirely in the code that is native to that specific platform. In the case of iOS, that means Objective-C or Swift. To build out the user interface for the application, you would be using the various native views and controls that are provided by iOS.

When an Ionic application is deployed to iOS natively, the underlying package does still use this same native code, but the bulk of the application itself is built with web code. In order to display a web-based user interface inside of a native iOS application, we make use of WKWebView. This is basically like launching a browser inside of the native application, and displaying our application inside of that. There is no browser interface visible, so there is no obvious difference between an application that is using Native UI controls for the user interface or a web view. The files displayed in the web view are accessed locally, so there is no need to have an Internet connection or to connect to a specific website/URL in order to display the content in the web view.

The biggest downside to using a web view to display the application is that the web view essentially becomes its own little world sandboxed away from the rest of the native application. Native APIs outside of the web view can still be accessed by the application inside of the web view, so this “sandboxing” isn’t much of an issue in that regard. The biggest point of difference is that unlike a “standard” native application, an application that uses a web view is primarily using this web view for computation and rendering the interface - the web view essentially becomes the “engine” for the application.

Fortunately, web browsers are quite powerful today, so as long as the application is designed well this limitation will often not matter. In some types of applications, this limitation can be a determining factor on whether or not a web-based approach is viable, but it isn’t for most. It does mean you have less leeway for mistakes though, so you do need to be careful you aren’t making costly performance mistakes. In the end, even with the full power of native code available a poorly designed application will still be slow.

With an understanding of what a web view is, and why that might be a limitation, let’s consider some of the positive aspects of using a web view.

Your applications will work wherever the web does

This is ultimately the primary benefit of using a web view to run an application, and most of the rest of the points I will be making are derived from this in some way.

By creating a web-based application, it’s just a standard web application that you can run wherever the web works. This gives you the ability to create cross-platform applications from a single codebase by default. There are no special compilers required to transform the code you wrote into code that works on a specific platform or special renderers that can display your application on each platform. It’s just standard web code that works on the web.

Using a web view allows you to ignore the specifics of the platform you want to run your application on. If the platform allows you to use a browser/web view then it can run your application. It doesn’t matter whether that is on a desktop browser, a mobile browser, a browser embedded in an iOS/Android application, a browser embedded in a native desktop application, a browser on a fridge or even on a Tesla.

A familiar development and debugging environment

A lot of the time, people who start developing mobile applications with Ionic (or any other web-based approach) are going to be those who have some experience with web development and want to utilise those skills for developing mobile applications.

Since we are able to use web views, which is essentially just a browser, the development experience is not really much different to just developing any kind of web-based application. Most of the development will be done directly through a desktop browser. Even when your application is deployed natively to iOS or Android or somewhere else, you can still test and debug using browser-based debugging tools that are exactly the same as those that you would use on a desktop browser.

Although some circumstances may require you to poke around the native codebase or logs using XCode or Android Studio (typically only in cases where you are integrating Native APIs), the vast majority of your development and debugging will happen in the browser.

Avoiding gatekeepers

I’ve had to edit this section down a few times and remove personal anecdotes since it was getting a bit too ranty and rambly. The short of it is that, personally, I despise that in the case of native iOS and Android applications a single external company (mostly Apple, the Google Play store seems to have fewer issues in this regard) essentially has full control over the distribution of your application and it can apply whatever arbitrary rules it likes. For example, you could spend months developing an application for iOS and ultimately Apple can just say “no” and refuse to put it on the store. There have even been many cases where applications that have previously been allowed on the app store have been disallowed by Apple and removed.

There have been many high profile cases of rejections and removals, but the more common case for smaller developers is running foul of the grey areas in Apple’s App Store Review Guidelines. Many of the guidelines are vague and open to interpretation, and ultimately it may depend on the particular reviewer you get for your application.

Many developers will find themselves falling victim to this particular requirement:

4.2 Minimum Functionality - Your app should include features, content, and UI that elevate it beyond a repackaged website. If your app is not particularly useful, unique, or “app-like,” it doesn’t belong on the App Store. If your App doesn’t provide some sort of lasting entertainment value, or is just plain creepy, it may not be accepted.

Which basically means that if your app doesn’t seem “appy” or useful enough to the reviewer, they might just reject the application on the grounds that it would be better suited as a website. This may be true in many circumstances, a lot of apps would provide a better experience as a website/PWA, but if you’ve invested a lot of time into developing an iOS application specifically then this could sting. This particular requirement often leads to circumstances where a developer will submit an application and get rejected on this basis, and then sometimes even submit the exact same application later and have it accepted.

Of course, companies may operate their businesses as they please and if we want to get our applications into their platform we need to play by their rules and conform to their standards. I think that it is too risky to have your business model rely entirely upon remaining in the good graces of a company that can arbitrarily apply whatever rules they like.

Using a web-based solution like Ionic does not avoid this situation entirely. If you want to deploy an Ionic application natively to iOS then you face all the same rules everybody else does. What a web-based solution does give you is more options. Since your application is made from web code that runs in a browser, if you have developed it for one platform then you have (mostly) already developed it for other platforms too. If your application is rejected by Apple you can still deploy that same application to the Google Play store. Or, you could publish independently on the web (although you may need to make some concessions if your application relied on interacting with Native APIs) and your iOS users could still access your application this way.

Personally, I’m hoping for a future where the vast majority of applications are Progressive Web Applications distributed through the open web, and mostly only specialty apps are actually installed onto the device and distributed through other means - just like what has happened with Desktop applications. Many of the day-to-day applications that we use which once existed as native desktop applications we now use web apps for instead.

Independence

As well as being free from the whims of an external company that controls the distribution of your application, we should also consider our reliance upon the company that has created the tool that we are using to build the application. What if the tool or framework you are using to build your applications suddenly decides to go in a different direction, perhaps changing their licensing model or drastically increasing prices? What if the company goes completely bankrupt, will the tool/framework continue to be maintained? Will you still be able to use it? Are the skills you have developed specific to just that one tool, or could you use what you have learned from using that tool and more easily use a new tool or approach?

This probably isn’t too much of a concern if you are using the native language of the device to develop applications (i.e. Objective-C/Swift for iOS or Java/Kotlin for Android). It is something you should consider if you are relying on an external tool/framework to build your application like Ionic, React Native, Xamarin, Flutter, or anything else.

Frankly, I don’t know enough about all of these tools (nor do I have enough time) to cover the “disaster scenarios” for each one, but let’s consider a “disaster” case for Ionic.

The Ionic team today are certainly leading the charge for using the web platform to build mobile applications. I think that the efforts of the Ionic team have shown just how viable the web is for building modern mobile applications. As it stands today, the people developing and maintaining Ionic belong to a strong and well-funded company.

But, nothing is impervious to the various factors that influence life and business. Even the popular Parse platform which had the backing of Facebookshut down unexpectedly leaving thousands of developers in the lurch. I think this is much less likely to ever be the case for Ionic since Ionic is the company’s business, whereas Parse to Facebook is not its primary business interest. But it needs to be considered.

What if next week the Ionic team in its entirety were to be suddenly abducted by aliens or some kind of malevolent cosmic artificial intelligence. What would happen to those of us who rely upon Ionic to build our applications?

This is, again, a case where I think the web-based approach provides a strong benefit. If the entire Ionic team were to disappear, in the short term, it would have almost no impact (except for people who are relying on the Appflow services). All of Ionic’s components are MIT licensed, open source, web components. There is no services, or renderers, or compilers, or any other dependencies required to run Ionic applications that would disappear along with the Ionic team. We can just use these components in a web-based application in any way we like.

Having little to no short term impact is a huge benefit which means there isn’t going to be an “Oh frick, what do we do now?” moment. In the medium term, there is more to consider. Now that Ionic’s components are just generic web components, these should remain useable for quite a long time before requiring any maintenance. But there is also other parts of Ionic to consider like the Angular, React, and Vue specific packages. Or perhaps iOS releases a new version of their operating system with an additional “side notch”. Eventually, some maintenance will be required. Everything is entirely open source, though, so as long people are willing to organise and make contributions then these packages should remain in good standing for a long time (or you could also perform the maintenance yourself if you or your team had the capability to do so).

In the long term, there would need to be some driving force pushing the web forward for mobile applications. The Ionic team have done an incredible job in developing Ionic into what it is today, but without them, there would need to be some kind of driving force for vision and innovation pushing the web forward as the years go by. Personally, I think we are now well past the point where the viability of the web for mobile apps has been proven, and this would happen naturally due to market forces.

We’ve mostly just touched on the idea of Ionic as a company disappearing or failing here, but I think this open source web-based approach also succeeds in the other factors I mentioned at the beginning of this section. Since Ionic is free and open source I think it’s unlikely we need to worry about sudden pricing or license changes. If Ionic did decide to “go in a different direction” we would still be able to use the open source code that Ionic is comprised of. Finally, the skills you develop in learning to build Ionic applications are highly transferable as in the end, we are just learning to build for the web, not the language of a specific “tool”.

Always bet on the web

If there is one technology that has stood the test of time it is the web. Technologies come and go, but HTML/CSS/JavaScript and the World Wide Web are likely going to be around for a long time to come.

The portability and longevity of the web is the key advantage of using web views to build mobile applications.

StencilJS is the technology behind the most recent version of the Ionic Framework, which allows Ionic’s components to be used with any framework or with no framework at all (opposed to the situation before where it was tied specifically to Angular). The reason StencilJS can be used to achieve this is that it provides a simplified way to build web components which are just native to the web, rather than to a specific framework.

You don’t need to use StencilJS in order to use Ionic, but we can use StencilJS if we want to create our own custom components that can be used anywhere. That means you could create a web component or web components that you could use in your framework of choice, but those same components could also be used with any other framework.

In the same way that Ionic provides a set of components to use in our applications, we could also provide our own set of components. This could be extremely useful in many situations, but especially where you are creating components that you intend to reuse across multiple projects. Imagine the time and effort you could save as a studio that develops mobile applications for clients and you slowly build up a collection of your own generic components that you can repurpose and reuse anywhere you like.

This also decouples a lot of the work you are doing from whatever framework you happen to be using at the time. In future, if you decide to change frameworks or adopt additional frameworks, you would be able to just directly drop in a lot of the work you have already done.

In this tutorial, we are going to walk through how you can create a collection of your own web components using StencilJS. We will then walk through how to use those components inside of an Ionic/Angular application, but you could use the same components elsewhere.

1. Create a new StencilJS Project

We can create multiple different types of StencilJS projects. Although StencilJS is a tool for building web components (not a framework), it can also be used as a kind of “pseudo-framework” for building applications in place of something like Angular/React/Vue.

A lot of the other StencilJS tutorials I have published on this site focus on that aspect, but in this case, we are going to be creating a StencilJS project specifically for the purpose of creating generic web components to be used elsewhere. This is easy to set up, as it is one of the default starting options when generating a new project.

Run the following command to generate a new StencilJS project:

npm init stencil

When prompted with the following options, choose component:

? Pick a starter › - Use arrow-keys. Return to submit.

   ionic-pwa     Everything you need to build fast, production ready PWAs
   app           Minimal starter for building a Stencil app or website
❯  component     Collection of web components that can be used anywhere

Fill out the additional prompts with information about your project, and then your project will be created. If you like, you can run the project right away to see it in the browser by making it your working directory and running:

npm start

You will find that the start project already includes an example component that you will see when you run the project:

Hello, World! I'm Stencil 'Don't call me a framework' JS

We will keep that component there to demonstrate that we can create a collection of multiple components to be used elsewhere, but we are also going to create our own additional component. This won’t be anything fancy, this is mostly for the sake of demonstrating the use of web components outside of StencilJS rather than learning the aspects of StencilJS itself.

2. Create the Web Components

To keep things simple, but still at least a little interesting, we are going to create a Marauder’s Map component. Harry Potter aficionados will already be familiar with the purpose of the such a map, but I’ll quickly summarise for those not familiar with the wizarding world. The Marauder’s Map displays the locations of people around Hogwarts Castle, but it is written in a special kind of magic ink such that not anybody can read it. Attempts to read the map without knowing the proper incantation will result in personal insults.

That is what our component will do, it will accept a reader prop and display insults to that person, e.g:

<my-marauders-mapreader="Josh"></my-marauders-map>

should result in:

Mr Moony presents his compliments to Josh, and begs them to keep their abnormally large nose out of other people's business.

Mr Prongs agrees with Mr Moony, and would like to add that Josh is an ugly git.

Mr Padfoot would like to register his astonishment that an idiot like that ever became a Professor.

Mr Wormtail bids Josh good day, and advises them to wash their hair, the slimeball.

Create new files at src/components/my-marauders-map/my-marauders-map.tsx and src/components/my-marauders-map/my-marauders-map.css

Add the following to src/components/my-marauders-map/my-marauders-map.tsx:

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

@Component({
  tag:"my-marauders-map",
  styleUrl:"my-marauders-map.css",
  shadow:true})exportclassMyMaraudersMap{/**
   * The first name
   */
  @Prop() reader: string;render(){return(<div><p>
          Mr Moony presents his compliments to {this.reader}, and begs them to
          keep their abnormally large nose out of other people's business.</p><p>
          Mr Prongs agrees with Mr Moony, and would like to add that
          {this.reader} is an ugly git.</p><p>
          Mr Padfoot would like to register his astonishment that an idiot like
          that ever became a Professor.</p><p>
          Mr Wormtail bids {this.reader} good day, and advises them to wash
          their hair, the slimeball.</p></div>);}}

The insults aren’t particularly creative here as they are just taken directly from Harry Potter but inserting the readers’ name in place of Snape’s, but you could perhaps come up with some more random/carefully crafted insults if you wanted.

To test out that this component behaves as you want it to, you can add it to the src/index.html file:

<!DOCTYPE html><htmldir="ltr"lang="en"><head><metacharset="utf-8"/><metaname="viewport"content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"/><title>Stencil Component Starter</title><scriptsrc="/build/mycomponent.js"></script></head><body><my-componentfirst="Stencil"last="'Don't call me a framework' JS"></my-component><my-marauders-mapreader="Josh"></my-marauders-map></body></html>

and then run the project with npm start. If all is well, you should see the following:

Hello, World! I'm Stencil 'Don't call me a framework' JS
Mr Moony presents his compliments to Josh, and begs them to keep their abnormally large nose out of other people's business.

Mr Prongs agrees with Mr Moony, and would like to add that Josh is an ugly git.

Mr Padfoot would like to register his astonishment that an idiot like that ever became a Professor.

Mr Wormtail bids Josh good day, and advises them to wash their hair, the slimeball.

3. Publish the Web Components

Before we can use these components in another project (an Ionic/Angular application in this particular case), we will need to publish them on npm - either publicly or privately.

You should first modify your package.json file to give your package an appropriate name and description (and any other details you want to fill out).

You can then build your web components using the following command:

npm run build

Then all that is left to do is publish the package to npm. If you already have your npm username set up you will just need to run:

npm publish

and the package will be published to npm. If you do not already have an NPM account set up, you will need to run the following command first:

npm adduser

Here is the package I published for this example (and you can use this package for the next part if you like): joshmorony-example-components

4. Use the Web Components

Now that our set of web components have been built and published, we can make use of them where we like. As I mentioned, we are going to cover the specific case of Ionic/Angular but you can find other framework integrations here: Framework Integration.

In order to use our web components in an Angular application, we must first install the package we published by running the following command in the Angular project:

npm install joshmorony-example-components --save

We must then modify main.ts to import and make a call to defineCustomElements:

import{ enableProdMode }from"@angular/core";import{ platformBrowserDynamic }from"@angular/platform-browser-dynamic";import{ AppModule }from"./app/app.module";import{ environment }from"./environments/environment";import{ defineCustomElements }from"joshmorony-example-components/dist/loader";if(environment.production){enableProdMode();}platformBrowserDynamic().bootstrapModule(AppModule).catch(err => console.log(err));defineCustomElements(window);

Any module that you want to use your web components in you must add the CUSTOM_ELEMENTS_SCHEMA to:

import{ NgModule,CUSTOM_ELEMENTS_SCHEMA}from"@angular/core";import{ CommonModule }from"@angular/common";import{ IonicModule }from"@ionic/angular";import{ FormsModule }from"@angular/forms";import{ RouterModule }from"@angular/router";import{ HomePage }from"./home.page";

@NgModule({
  imports:[
    CommonModule,
    FormsModule,
    IonicModule,
    RouterModule.forChild([{
        path:"",
        component: HomePage
      }])],
  schemas:[CUSTOM_ELEMENTS_SCHEMA],
  declarations:[HomePage]})exportclassHomePageModule{}

Finally, we can just drop the web component in wherever we want to use it now:

<ion-header><ion-toolbar><ion-title>
      Ionic Blank
    </ion-title></ion-toolbar></ion-header><ion-content><divclass="ion-padding"><my-marauders-mapreader="Josh"></my-marauders-map></div></ion-content>

Summary

There is a little more work involved in doing this initially rather than just creating a custom component directly in the Angular application (or whatever framework you are using). However, there are a lot of benefits if you do take the time to learn StencilJS and to create generic web components that can be used anywhere.

We’ve recently been discussing various ways to manage state in a StencilJS application, including using Stencil State Tunnel and Redux. We’ve specifically been considering the context of building Ionic applications built with StencilJS, but these concepts apply to any StencilJS application.

We might implement some kind of “state management” solution to keep track of things like:

• Settings values that can be accessed throughout the application
• A logged in user’s data
• Posts, articles, comments etc.

However, some applications may benefit from a simpler solution rather than a full-featured state management solution like Redux. If you have a background with Angular then you may be used to using services/providers/injectable to fulfill this role. Angular has the concept of an @Injectable built-in, which we can use to create a service that can share data/methods throughout our application.

StencilJS is not as “opinionated” as Angular - remember that whilst StencilJS can afford us a lot of the benefits of a traditional framework, it isn’t actually a framework (it is a web component compiler) and it doesn’t have a bunch of the built-in features that Angular does.

Although this kind of functionality isn’t baked into StencilJS, it is actually quite straight-forward to implement with vanilla JavaScript.

The method of sharing data using a class that we are discussing is commonly referred to as a singleton pattern and it is a technique that has been around for a long time. The basic idea is that we want to share a single instance of a class among multiple pages/components/services, such that they are all accessing the same methods and data.

A class is like a blueprint for creating objects, and we can create multiple objects from a single class. For example, we can do this:

let myService =newMyService()

To create a new object based on the MyService class, and we can do this as many times as we like. Each time we do it, we are creating a completely separate and independent object. With the singleton pattern, we would just do this once and create a single object based on the class that is shared throughout our entire application. In this way, that shared singleton object provides the same methods and data no matter what is accessing it or where it is accessing it from.

Creating a Singleton Service in StencilJS

The concept is simple enough: instantiate a single object from a class and share that object throughout the application. Let’s take a look at what that might actually look like though. We will create a simple dummy service to demonstrate.

Create a file at src/services/my-service.ts and add the following:

import{ MyDataType }from"../interfaces/my-data";classMyServiceController{public myData: MyDataType[];constructor(){}asyncload(){if(this.myData){returnthis.myData;}else{// Load data and then...returnthis.myData;}}asyncgetData(){const data =awaitthis.load();return data;}addData(data){this.myData.push(data);}}exportconst MyService =newMyServiceController();

At this point, if you are familiar with Angular, you will probably that this looks almost identical to what you would do in Angular - except that there is no @Injectable decorator, and we are exporting an instance of the class at the bottom.

We are just using some dummy methods and data here, but the general idea is that we have a service that is keeping track of some data (maybe posts or todos). We have the myData class member that will store the data, we have a method to load an initial set of data, we have a addData method for adding more data, and a getData method to return the current set of data.

We might want to make use of the methods/data available in this class in multiple pages/components in our StencilJS application. Perhaps from one page, we will want to call the getData method to get all of the current data, but we might also want to call the addData method from a different page and have that data made available to the page making the getData call.

To achieve this, we create a new instance of the service like this:

exportconst MyService =newMyServiceController();

We not only create a new instance of MyServiceController, we also export it so that we will be able to import this object elsewhere in our application. Notice that we declare the object using const instead of say var or let. By using const we ensure that our singleton service can’t be overwritten, which is the point of a singleton service - we want to declare a single instance and use that throughout the life of the application. It’s not required to use the const keyword, but it does help enforce the “singleton-ness” of the object.

Now that we have our service, we just need to be able to make use of it throughout the application. To do that, you will be able to import it anywhere like this:

import{ MyService }from"../../services/my-service";

and then in the component that you have imported MyService into, you will immediately be able to make use of all of the data/methods that the service provides:

MyService.addData(data);

this.data =await MyService.getData();

We will be able to import this service in any of our pages/component/services and we will be sharing the same instance. If we addData in one component, and then later use getData from a different component, the data added by one component will be available to the other.

Summary

This approach isn’t perhaps as robust or scalable as using a full state management solution like Redux, but it is a lot simpler and often an application will not require anything more advanced than a simple singleton to manage state. Although this kind of functionality isn’t available out of the box like it is with a full/opinionated framework like Angular, it is quite simple to achieve with just standard ES6 JavaScript classes.

Over the past few weeks we have been covering various aspects of state management in Ionic applications - both with Angular (using NgRx) and StencilJS (using Redux).

So far, we have only covered the basics concepts of Ionic + StencilJS + Redux, but this tutorial is going to jump straight into a realistic example of using Redux for an Ionic/StencilJS application. We will be using Redux to store data loaded from a local JSON file using the Fetch API (although you could just as easily make the request to a real server). With the data loaded into the Redux store, we will be able to access the state/data we need from the components in our application.

We will also handle loading and error/failure states so that our application is able to respond accordingly to these situations (e.g. we might want to show a loading overlay whilst the data is in the process of being loaded, or we might want to display an error message to the user if the data fails to load).

Although we will be using the Ionic PWA Toolkit in this example, these concepts will apply generically to any StencilJS application.

Before We Get Started

This is an advanced tutorial, and if you don’t already have an understanding of the basic concepts of Redux, I would highly recommend that you watch this video first: What is Redux?.

I’ll preface this tutorial by saying that you don’t necessarily need to use Redux in your StencilJS applications. You might not find the complexity worthwhile for simple applications and may find it easier to manage data/state through services - especially if you are more at the beginner level.

However, although there is a bit more work involved in setting up and learning a state management solution like Redux, it does provide powerful benefits.

The Basic Concept

If you’re reading this you should already have somewhat of an understanding behind the basic idea of how actions and reducers work (or at least what their role is). An action describes some intent (e.g. SET_FILTER), and a reducer takes in the current state and an action and produces a new state that reflects the result of that action.

Since I have already given you the context that we are going to be loading in some data from a JSON file, you might expect that we would just need to create a single action like:

• LOAD_DATA

However, we will actually be creating three separate actions to handle this process:

• LOAD_DATA_BEGIN
• LOAD_DATA_SUCCESS
• LOAD_DATA_FAILURE

First, we will dispatch a LOAD_DATA_BEGIN action. Depending on the success of our fetch request, we will then either dispatch a LOAD_DATA_SUCCESS action or a LOAD_DATA_FAILURE action. We do this because we don’t just immediately get the data when we load it. First, there is a period of time whilst the data is loading (e.g. a request to some API is in progress) in which we don’t have access to the data - we might want to display something specific in our application during this time. Whilst the data will likely eventually load in most of the time, it is possible that an error could occur (e.g. there was a bug in your code or the server you are requesting data from is down). In that case, we probably also want to make sure that our application handles that situation appropriately.

Using these three actions will allow us to more accurately describe the state of our application, and result in a more bullet-proof solution that allows us to handle multiple different scenarios that can arise from loading data.

Installing Redux

Once you have a StencilJS project created (it doesn’t matter whether you choose an Ionic PWA or not, that is just what I will be using in the example code) you will need to install the following packages:

npm install redux --save

This will, probably unsurprisingly, install Redux itself.

npm install redux-thunk --save

This is additional middleware for Redux, which is basically like a plugin that adds extra functionality. Redux Thunk will allow us to use an asynchronous function as an action (which will allow us to create an action that launches our asynchronous fetch request).

npm install redux-logger --save

This is some more middleware that will provide us with some nice debug log messages - this is extremely useful as it allows us to easily see what actions are being triggered and what the resulting state looks like.

npm install @stencil/redux --save

Finally, we have the StencilJS package for Redux which basically just provides functionality for integrating Redux into our StencilJS components.

Setting up Redux in StencilJS

Before we get into the specifics of implementing our data loading solution, let’s first just get a basic implementation of Redux set up in our StencilJS project. We are going to need to create a few files/folders and add a bit of configuration for our Redux store.

Create a file at src/store/index.ts and add the following:

import{ createStore, applyMiddleware }from"redux";import rootReducer from"../reducers/index";import thunk from"redux-thunk";import logger from"redux-logger";constconfigureStore=(preloadedState: any)=>createStore(rootReducer, preloadedState,applyMiddleware(thunk, logger));export{ configureStore };

When using Redux, we have a single “store” that stores all of the state for our application. We use this file to configure that store, which involves supplying it with the reducers we will create, any initial state that we want, and any middleware that we want to use. This will likely look pretty similar for most implementations, the only “special” thing we are really doing here is setting up our thunk and logger middleware. The reducers are being pulled in from a different file that we will create soon.

Modify your root component at src/components/app-root/app-root.tsx to configure the store:

import{ Component, Prop }from"@stencil/core";import{ Store }from"@stencil/redux";import{ configureStore }from"../../store/index";

@Component({
  tag:"app-root",
  styleUrl:"app-root.css"})exportclassAppRoot{
  @Prop({ context:"store"}) store: Store;componentWillLoad(){this.store.setStore(configureStore({}));}render(){return(<ion-app><ion-router useHash={false}><ion-route url="/" component="app-home"/><ion-route url="/profile/:name" component="app-profile"/></ion-router><ion-nav /></ion-app>);}}

We also need to do a little configuration for the store in our root component for the application. We import Store from the StencilJS package for redux and set it up as a @Prop() in the component. Then, inside of the componentWillLoad lifecycle hook, we make a call to the setStore method using the configureStore function we just set up in the previous file.

Create a file at src/reducers/index.ts and add the following:

import dataReducer from"./data";import{ combineReducers }from"redux";const rootReducer =(combineReducers as any)({
  dataReducer
});exportdefault rootReducer;

Now we need to set up our reducers (which we referenced in our store file). This index.ts file will combine all of the reducers we create for our application, but in this case, we are just going to have a single dataReducer.

We are going to set up a simple version of our dataReducer that is being imported now, but we will focus on the actual implementation of the reducer later.

Create a file at src/reducers/data.ts and add the following:

import{ Actions, ActionTypes }from"../actions/index";interfaceDataState{
  items: string[];
  loading: boolean;
  error: any;}constgetInitialState=()=>{return{
    items:[],
    loading:false,
    error:null};};const dataReducer =(
  state: DataState =getInitialState(),
  action: ActionTypes
)=>{switch(action.type){// handle different actions}return state;};exportdefault dataReducer;

This is the basic outline of our reducer, but we have removed the implementation details - this is what most reducers will look like to begin with. We set up a DataState interface to represent the type of data/state we want to hold for this reducer - an array of items that will be simple strings, a loading state that will be true when the data is in the process of being loaded, and an error for holding any errors that occur.

We then define a getInitialState function that returns the initial state we want to use - most of the time this is just going to be empty/blank/null values.

Then we have the dataReducer itself, which takes in the state and an action. It will then switch between the various possible actions (in our case this will be LOAD_DATA_BEGIN, LOAD_DATA_SUCCESS, and LOAD_DATA_FAILURE). The responsibility of the reducer is to return some new state based on the current state and the action that has been supplied. Again, if you aren’t already reasonably familiar with these general concepts I would recommend watching my Redux video first.

Next, we need to set up our actions that will be passed into the reducer.

Create a file at src/actions/data.ts and add the following:

import{ Actions }from"../actions/index";exportinterfaceLoadDataBeginAction{
  type: Actions.LOAD_DATA_BEGIN;}exportconstloadDataBegin=()=>async(dispatch, _getState)=>{returndispatch({
    type: Actions.LOAD_DATA_BEGIN});};exportinterfaceLoadDataSuccessAction{
  type: Actions.LOAD_DATA_SUCCESS;
  payload: any;}exportconstloadDataSuccess= data =>async(dispatch, _getState)=>{returndispatch({
    type: Actions.LOAD_DATA_SUCCESS,
    payload:{ data }});};exportinterfaceLoadDataFailureAction{
  type: Actions.LOAD_DATA_FAILURE;
  payload: any;}exportconstloadDataFailure= error =>async(dispatch, _getState)=>{returndispatch({
    type: Actions.LOAD_DATA_FAILURE,
    payload:{ error }});};

First, we import Actions from the index file for the actions that we will create in just a moment - in this file we will provide some consistent names for our actions so that if we accidentally make a typo when typing out LOAD_DATA_BEGIN or any of the other actions (I seem to have a habit of typing BEING instead of BEGIN), we are immediately going to see the error if we are using something like Visual Studio Code (because the property won’t exist on Actions, as opposed to just typing out a string value where the code editor wouldn’t know that it was a mistake).

Then we create our three actions inside of this file, and for each action, we create an interface to describe its structure. Each action requires a type that will describe what the action does (e.g. LOAD_DATA_BEGIN) and it can also optionally have a payload which can contain additional data. The payload in our case might be the items we want to load in for LOAD_DATA_SUCCESS or the error that occurred for LOAD_DATA_FAILURE. No payload is required for LOAD_DATA_BEGIN because it is just launching the process for loading the data.

Notice that the actions with a payload have that payload passed into the function:

exportconstloadDataSuccess= data =>async(dispatch, _getState)=>{exportconstloadDataFailure= error =>async(dispatch, _getState)=>{

whereas the action with no payload does not pass in any parameters:

exportconstloadDataBegin=()=>async(dispatch, _getState)=>{

Now we just need to create that actions index file.

Create a file at src/actions/index.ts and add the following:

import{
  LoadDataBeginAction,
  LoadDataSuccessAction,
  LoadDataFailureAction
}from"./data";// Keep this type updated with each known actionexport type ActionTypes =| LoadDataBeginAction
  | LoadDataSuccessAction
  | LoadDataFailureAction;exportenum Actions {LOAD_DATA_BEGIN="LOAD_DATA_BEGIN",LOAD_DATA_SUCCESS="LOAD_DATA_SUCCESS",LOAD_DATA_FAILURE="LOAD_DATA_FAILURE"}

This file doesn’t actually do much, its main purpose is to list the various available actions so that they can be imported and used elsewhere. Again, if you are using something like Visual Studio Code, this would allow you to just start typing:

Actions.

In another file where you are importing Actions and it will immediately pop up with a list of all of the available actions. This saves you time looking them up all the time, and it also prevents mistakes through typos.

Create Test Data

We’ve got the basic structure for our Redux store set up now, but before we implement the rest of it we are going to need some test data. As I mentioned, we are going to make a GET request with fetch, but we are just going to be using a local JSON file as the data source. You can modify this data with your own file, or you could make a real HTTP request to some API if you prefer.

Create a file at src/assets/test-data.json and add the following:

{"items":["car","bike","shoe","grape","phone","bread","valyrian steel","hat","watch"]}

Implementing the Actions and Reducer

Now we get to the bit that actually makes our actions/reducer do something interesting. Let’s consider how we want this to work.

• When we dispatch a LOAD_DATA_BEGIN action we want to trigger the fetch request and set the loading state to true. The following two actions should be dispatched automatically depending on whether or not the data loading succeeds.
• When the LOAD_DATA_SUCCESS action is dispatched, we want to set the loading state to false and we want to set the items state to the data payload that has been loaded in
• When the LOAD_DATA_FAILURE action is dispatched, we want to set the loading state to false and we want to set the error state to whatever error occurred

Let’s begin by making our dataReducer reflect this intent.

Modify src/reducers/data.ts to reflect the following:

import{ Actions, ActionTypes }from"../actions/index";interfaceDataState{
  items: string[];
  loading: boolean;
  error: any;}constgetInitialState=()=>{return{
    items:[],
    loading:false,
    error:null};};const dataReducer =(
  state: DataState =getInitialState(),
  action: ActionTypes
)=>{switch(action.type){case Actions.LOAD_DATA_BEGIN:{return{...state,
        loading:true,
        error:null};}case Actions.LOAD_DATA_SUCCESS:{return{...state,
        loading:false,
        items: action.payload.data
      };}case Actions.LOAD_DATA_FAILURE:{return{...state,
        loading:false,
        error: action.payload.error
      };}}return state;};exportdefault dataReducer;

Remember that our reducer does not modify the existing state, it creates a new state. This is why we would return something like this:

return{...state
      };

It uses the spread operator to take all of the properties out of the existing state, and add them to the new state object that we are returning. In this sense, we are creating a new state that exactly reflects the previous state not just returning the existing state. However, we don’t want the state to be unchanged, that is why we do this:

return{...state,
        loading:false,
        items: action.payload.data
      };

First, we reconstruct the old state inside of our new state, but then we specifically overwrite the loading and items properties. Therefore, we aren’t modifying the existing state (this is not allowed in Redux), we are supplying a new different state.

Each of our actions supplies new state properties to reflect what we wanted to achieve with those actions, using the payload that is passed into it if necessary. But where does that payload come from? Where is the fetch request happening? So far, we have done a whole lot of describing and not much doing. Let’s finally add the key ingredient.

Remember before how we set up the redux-thunk middleware? This was so that we could use an asynchronous function as an action. Let’s create that function now.

Modify src/actions/data.ts to reflect the following:

import{ Actions }from"../actions/index";interfaceDataResponse{
  items: string[];}exportfunctionloadData(){returnasync dispatch =>{// Trigger the LOAD_DATA_BEGIN actiondispatch(loadDataBegin());try{let response =awaitfetch("/assets/test-data.json");handleErrors(response);let json: DataResponse =await response.json();// Trigger the LOAD_DATA_SUCCESS actiondispatch(loadDataSuccess(json.items));return json.items;}catch(error){// Trigger the LOAD_DATA_FAILURE actiondispatch(loadDataFailure(error));}};}functionhandleErrors(response){if(!response.ok){thrownewError(response.statusText);}return response;}// ACTIONSexportinterfaceLoadDataBeginAction{
  type: Actions.LOAD_DATA_BEGIN;}exportconstloadDataBegin=()=>async(dispatch, _getState)=>{returndispatch({
    type: Actions.LOAD_DATA_BEGIN});};exportinterfaceLoadDataSuccessAction{
  type: Actions.LOAD_DATA_SUCCESS;
  payload: any;}exportconstloadDataSuccess= data =>async(dispatch, _getState)=>{returndispatch({
    type: Actions.LOAD_DATA_SUCCESS,
    payload:{ data }});};exportinterfaceLoadDataFailureAction{
  type: Actions.LOAD_DATA_FAILURE;
  payload: any;}exportconstloadDataFailure= error =>async(dispatch, _getState)=>{returndispatch({
    type: Actions.LOAD_DATA_FAILURE,
    payload:{ error }});};

The key change in this file is this:

exportfunctionloadData(){returnasync dispatch =>{// Trigger the LOAD_DATA_BEGIN actiondispatch(loadDataBegin());try{let response =awaitfetch("/assets/test-data.json");handleErrors(response);let json: DataResponse =await response.json();// Trigger the LOAD_DATA_SUCCESS actiondispatch(loadDataSuccess(json.items));return json.items;}catch(error){// Trigger the LOAD_DATA_FAILURE actiondispatch(loadDataFailure(error));}};}functionhandleErrors(response){if(!response.ok){thrownewError(response.statusText);}return response;}

We are creating a loadData() function that, when called, will dispatch the LOAD_DATA_BEGIN action using the action we have already created for it further below in the file. This will then make that fetch request and if it is successful it will dispatch the LOAD_DATA_SUCCESS action whilst also passing the items that were loaded into it. If an error occurs during this process, which will be caught by our try/catch block, then the LOAD_DATA_FAILURE action will be dispatched instead.

Now all we need to do is call that loadData() method to kick off this whole process.

Consuming State in Your Components

We’re almost done! But, there is one more thing we need to take care of. We have everything set up, but we still need to use it somewhere. We’re going to walk through an example of triggering our load and consuming state from a Redux store in the home page of a StencilJS/Ionic application.

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

import{ Component, State, Prop }from"@stencil/core";import{ Store, Action }from"@stencil/redux";import{ loadData }from"../../actions/data";

@Component({
  tag:"app-home",
  styleUrl:"app-home.css"})exportclassAppHome{
  @State() items: any;
  @State() loading: boolean;
  @State() error: any;

  @Prop({ context:"store"}) store: Store;
  loadData: Action;componentWillLoad(){this.store.mapStateToProps(this, state =>{const{
        dataReducer:{ items, loading, error }}= state;return{
        items,
        loading,
        error
      };});this.store.mapDispatchToProps(this,{
      loadData
    });}componentDidLoad(){this.loadData();}render(){return[<ion-header><ion-toolbar color="danger"><ion-title>Ionic + StencilJS + Redux</ion-title></ion-toolbar></ion-header>,<ion-content><ion-list lines="none">{this.items.map(item =>(<ion-item><ion-label>{item}</ion-label></ion-item>))}</ion-list></ion-content>];}}

We have set up three member variables with the StencilJS @State() decorator (which causes our template to re-render to reflect changes each time any of these values change). We then use mapStateToProps from the store to map the state from the store onto those member variables, which will make them accessible to us in the component. There is a lot of weird/fancy destructuring assignment syntax going on here, but it’s basically just a neater way to write this.items = state.dataReducer.items for each piece of state that we want to set up. You can learn more about destructuring assignments here if you like: Understanding { Destructuring } = Assignment.

With that done, we can just simply access this.items, this.loading, and this.error in our component and it will reflect whatever values they are supposed to contain. We do still need to call that loadData() function somewhere, though.

To do that, we set up a member variable called loadData. We then use the mapDispatchToProps method from the store to assign the loadData method imported from our actions file to the member variable. Then we just simply call this.loadData() from our componentDidLoad method to automatically trigger the load process as soon as the component has loaded.

If you check out the console logs when running your application you should now see the various actions being triggered:

This is due to our use of redux-logger which is really cool because it allows you to see the previous state and then how the current action changed the new state.

Just for a bit of fun, let’s purposefully make our load request fail. If we modify this call:

let response =awaitfetch("/assets/test-data.json");

to this:

let response =awaitfetch("/wrong/path/test-data.json");

It is going to fail. Let’s see what happens to our Redux store in that scenario:

You can see that the LOAD_DATA_FAILURE action is triggered and the appropriate error is supplied. We haven’t implemented it in this example, but we could then easily make use of this new state in our component to display an appropriate error message to the user since it would be available through this.error.

Summary

Rather than having to manually manage state and write conditions for various things that might happen, this whole process is now kind of “out of sight, out of mind”. It requires a little more legwork initially, but now we can just trigger a single loadData() function, and our component will reflect an appropriate state - no matter if the data loading succeeds or fails.

A tabbed navigation interface is very commonly used in mobile applications and, as with most things user interface related, the Ionic web components make implementing this kind of interface relatively easy. We can make use of the <ion-tabs>, <ion-tab>, <ion-tab-bar>, and <ion-tab-button> components to create an interface with multiple tabs that display different components that we can easily switch between:

In this tutorial, we are going to look at two different approaches to implementing tab navigation in an Ionic & StencilJS application. The first will be a basic implementation that allows for switching between components using tabbed navigation, but each individual tab will be limited to displaying just a single component.

The second approprach will provide each tab with its own navigation system, allowing for additional pages/components to be pushed within an individual tab. This would allow you to create a master/detail navigation pattern (or pretty much anything else) within an individual tab.

Before we Get Started

This tutorial will assume that you already have a grasp on the basics of building Ionic applications with StencilJS. If you need to learn more of the basics first, you might want to check out my other StencilJS tutorials.

1. Getting Ready

We will be using, more or less, the same project structure for both of our example. If you want to follow along with the examples, I would recommend setting up a new Ionic/StencilJS project with the following components:

• app-root
• app-tabs
• app-home
• app-profile
• app-detail

With both approaches, the general structure is mostly the same. We have our app-root component which will contain our routing information as usual. The app-tabs component will set up the tabs interface and the app-home, app-profile, and app-detail components will be used inside of the tabs interface.

For the basic example, we will just be using app-home and app-profile inside of the tabs interface and providing the ability to switch between those. In the advanced example, we will add the ability to “push” the additional app-detail page inside of the tab that contains app-profile.

2. Basic Tabs

This first example is going to demonstrate a basic implementation of tabbed navigation that will allow you to switch between multiple components in a tab view, but you will not be able to navigate within individual tabs.

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

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

@Component({
  tag:"app-tabs",
  styleUrl:"app-tabs.css"})exportclassAppTabs{render(){return[<ion-tabs><ion-tab tab="tab-home" component="app-home"/><ion-tab tab="tab-profile" component="app-profile"/><ion-tab-bar slot="bottom"><ion-tab-button tab="tab-home"><ion-icon name="map"/><ion-label>Home</ion-label></ion-tab-button><ion-tab-button tab="tab-profile"><ion-icon name="information-circle"/><ion-label>Profile</ion-label></ion-tab-button></ion-tab-bar></ion-tabs>];}}

This sets up the general structure for our tabs. We define everything inside of the <ion-tabs> components, including each individual tab which is created with <ion-tab> and then the <ion-tab-bar> which provides the buttons for switching between the various tabs. Notice that we give a name to each <ion-tab> using the tab property, and then we supply that name to the <ion-tab-button> so that it knows which tab to activate when clicked.

We also assign the component that the tab should display by using the component property, and just providing the tag of the component that we want to use. Now we just need to set up the routing.

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

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

@Component({
  tag:"app-root",
  styleUrl:"app-root.css"})exportclassAppRoot{render(){return(<ion-app><ion-router useHash={false}><ion-route component="app-tabs"><ion-route url="/" component="tab-home"/><ion-route url="/profile" component="tab-profile"/></ion-route></ion-router><ion-nav /></ion-app>);}}

We create a route for our app-tabs component similarly to how we would create a normal route, except that there is no url attached directly to it. Instead, we provide additional routes inside of the route for app-tabs that connects particular URLs to our tabs. Notice that the component we supply to the routes is the tab name we gave them in app-tabs not the actual component itself - we want the router to active the tab that contains the component, not the component itself.

That’s all we need to do for a basic tabs set up. If you load the application now it should load up the default / route, which will display the tab-home tab in our tabbed navigation. You should then be able to switch back and forth between the two tabs.

3. Advanced Tabs

This next implementation will give each tab its own <ion-nav> component, which will allow it to provide full navigation capabilities within individual tabs. This means that each tab can maintain its own navigation, and you could navigate between multiple pages/components within an individual tab.

There are only a few minor modifications required in order to get this working. Let’s take a look.

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

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

@Component({
  tag:"app-tabs",
  styleUrl:"app-tabs.css"})exportclassAppTabs{render(){return[<ion-tabs><ion-tab tab="tab-home"><ion-nav /></ion-tab><ion-tab tab="tab-profile"><ion-nav /></ion-tab><ion-tab-bar slot="bottom"><ion-tab-button tab="tab-home"><ion-icon name="map"/><ion-label>Home</ion-label></ion-tab-button><ion-tab-button tab="tab-profile"><ion-icon name="information-circle"/><ion-label>Profile</ion-label></ion-tab-button></ion-tab-bar></ion-tabs>];}}

This is more or less the same as the basic example, except that instead of assigning a component directly to the <ion-tab> we add an <ion-nav> component inside of the tab. Now let’s up the routing.

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

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

@Component({
  tag:"app-root",
  styleUrl:"app-root.css"})exportclassAppRoot{render(){return(<ion-app><ion-router useHash={false}><ion-route component="app-tabs"><ion-route url="/" component="tab-home"><ion-route component="app-home"/></ion-route><ion-route url="/profile" component="tab-profile"><ion-route component="app-profile"/><ion-route url="/detail" component="app-detail"/></ion-route></ion-route></ion-router><ion-nav /></ion-app>);}}

Again, pretty similar, except that now we have one additional layer or nesting for our routes. Inside of the route for each individual tab, we supply further routes to determine what to display in that tab. Let’s take a closer look at the tab-profile tab which is the interesting one here:

<ion-route url="/profile" component="tab-profile"><ion-route component="app-profile"/><ion-route url="/detail" component="app-detail"/></ion-route>