Using Ionic Framework with SharePoint Framework (SPFx)

For those that know me, you might have heard about my extensive use of Ionic Framework, a mobile app platform, to build various side projects including BrewZap and HappenZap. If you aren’t familiar with Ionic Framework, it’s a node.js based development framework for mobile apps. Ionic was originally built using AngularJS and then modern versions of Angular. With it’s recent release of 4.0.0, Ionic has made the shift to web components. This has allowed Ionic to support other frameworks such as React and Vue. I’ve been trying to get Ionic Framework to work inside SPFx on and off for about two years now. Now with SPFx 1.8 and React 16.7.0, all of the dependencies have lined up and it is in fact possible using the new Ionic React.

How to use Ionic React in SPFx

Let’s go out of order and start with the “How” before we answer the “Why” because that could be more open for debate. First, start a new SPFx project with yo. I assume you already know how to do that if you are reading this post. Next, we need to install @ionic/react and some other packages (reference).

npm install @ionic/react react-router react-router-dom @types/react-router @types/react-router-dom

That installs the dependencies, you can try and run your SPFx project, but you won’t be successful yet. Ionic React requires a newer version of TypeScript. We’ll use 3.3 in our case. To do that edit package.json and remove your @microsoft/rush-stack-compiler-2.7 devDependency. Replace it with 3.3, but use version 0.1.6 because 0.1.7 doesn’t currently work with SPFx. Here is what the line looks like.

"@microsoft/rush-stack-compiler-3.3": "0.1.6",

Next, edit tsconfig.json and change the extends line to use version 3.3.

"extends": "./node_modules/@microsoft/rush-stack-compiler-3.3/includes/tsconfig-web.json", 

We’re almost ready to start using Ionic React at this point, but there is one more issue to take care of. If you run gulp serve right now, you will get errors about it not being able to find source files inside @ionic/react. That one took me a while to fix. However, I found the solution from a similar issue that was occurring when trying to use Kendo in SPFx. The fix involves an update to gulpfile.js with an exclusion to the source map loader. Replace the contents of your gulpfile.js with the following:

'use strict';

const gulp = require('gulp');
const build = require('@microsoft/sp-build-web');
const path = require('path');

build.addSuppression(`Warning - [sass] The local CSS class 'ms-Grid' is not camelCase and will not be type-safe.`);

build.configureWebpack.mergeConfig({

    additionalConfiguration: (generatedConfiguration) => {

        generatedConfiguration.module.rules.map(rule => {
            if (rule.use.indexOf("source-map-loader") != -1) {
                rule.exclude = path.resolve(__dirname, "node_modules");
            }
        });

        return generatedConfiguration;
    }
});

build.initialize(gulp);

Now you are ready to start adding your Ionic Framework code. In your web part’s .tsx file, add the following imports for the Ionic CSS.

import '@ionic/core/css/core.css';
import '@ionic/core/css/ionic.bundle.css';

Next, you need to determine what controls you might want to use. I’m going to add a handful of interesting controls. Since Ionic React is in early betas, there isn’t a lot of documentation on it yet. However, the Angular and Core versions are well documented so you can go there to see what the UI components look like.

import {
  IonCard,
  IonCardHeader,
  IonCardTitle,
  IonCardSubtitle,
  IonButton,
  IonModal,
  IonHeader, IonToolbar, IonButtons, IonMenuButton, IonTitle, IonIcon, IonPopover
} from '@ionic/react';

Now you can reference your Ionic React components just like you would any other component.

Examples of Ionic Framework running in SPFx

Here are some examples of using the Ionic Framework UI components inside of SPFx web parts.

This first example renders a card with a header and placeholder image.

        <IonCard>
          <IonCardHeader>
            <IonCardSubtitle>Welcome to Ionic</IonCardSubtitle>
            <IonCardTitle>Running on React</IonCardTitle>
          </IonCardHeader>
          <IonCardContent>
            <img src="https://via.placeholder.com/500x200"></img>
            <IonLabel>
              This is some card content.
            </IonLabel>
          </IonCardContent>
        </IonCard>

To demonstrate the list capability, I created a simple array of data.

private sampleData = [
    {
      id: 1,
      image_url: 'https://via.placeholder.com/150',
      name: "Item 1"
    },
    {
      id: 2,
      image_url: 'https://via.placeholder.com/150',
      name: "Item 2"
    },
    {
      id: 3,
      image_url: 'https://via.placeholder.com/150',
      name: "Item 3"
    },
    {
      id: 4,
      image_url: 'https://via.placeholder.com/150',
      name: "Item 4"
    },
    {
      id: 5,
      image_url: 'https://via.placeholder.com/150',
      name: "Item 5"
    }
  ];

Then I use the IonList control along with a map to render each item. IonAvatar is useful to display user pictures with rounded corners.

        <IonList>
          {
            this.sampleData.map(item => (
              <IonItem>
                <IonAvatar slot="start">
                  <img src={item.image_url}></img>
                </IonAvatar>
                <IonLabel>
                  {item.name}
                </IonLabel>
              </IonItem>
            ))
          }
        </IonList>

Here is what the web part looks like showing off some additional controls such as buttons.

For a more meaningful example, I built some web parts that use data from BrewZap. I was able to adapt my Angular code to use similar controls in Ionic React. That’s an IonSegment control at the top that lets you toggle between views.

I bound our event data using repeating IonCard elements.

If you are looking for more code samples of Ionic React, be sue and check out the Ionic Conference app. It uses a lot of common components and it will help you understand the syntax.

Check out my repo on GitHub for my code samples and a working starter project.

Why use Ionic Framework in SPFx?

At this point, you might be thinking that’s neat, but I already have Office Fabric and it’s finally running on version 6.156 in SPFx. That’s true. Let’s go through some of the reasons why I think this is significant.

• Adds variety to your UI component library – Ionic brings you a variety of UI components including input, toolbars, menus, modals, cards, lists, and more.
• Mobile by default – Ionic Framework is a mobile-first framework. That means the components will flow nicely for whatever screen you use.
• Device specific rendering – Ionic Framework renders it UX components based on whatever device you are looking like. That’s means you get iOS-style components on your iPhone and you get Material Design on Android. In the browser, you’ll get Material Design as well.
• Icons – who can’t use more icons? Ionic Framework includes hundreds of icons. It even includes icons for things like beer and wine for when you are building that business-critical happy hour web part.
• Built on top of web components – web components are the foreseeable future for UI frameworks. I’m really hoping Office Fabric adopts them so that SPFx is not tied to a single JavaScript framework. Technically you could use Ionic without using the Fabric React shim too.
• Shared code base between mobile apps and SPFX? – If you’re code is well structured in components, it’s possible.

I’m definitely excited about the possibilities this might open up. I’m not recommending you go out and dump Fabric React for Ionic. However, I think there are scenarios where this might be useful. It’s still in early beta so you might run into issues. Give it a try though and see what you think.