What is Ionic Framework?​

First off, if you're new here, welcome! Ionic Framework is a free and open source component library for building apps that run on iOS, Android, Electron, and the Web. Write your app once using familiar technologies (HTML, CSS, JavaScript) and deploy to any platform.

Along with the UI components, Ionic Framework also provides a command line tool for creating new apps, as well as deploying to the various platforms we support.

In this guide, we will go over the basics of both Vue and Ionic Framework, including any Ionic Framework specific features. If you are familiar with Vue, enjoy the guide and learn something new about Ionic Framework. If you are not familiar with either, no worries! This guide will cover the basics and provide enough information to get an app up and running.

Creating a project with the Ionic CLI​

To begin, let's install the latest version of the Ionic CLI.

npm install -g @ionic/cli@latest

From here, the global commandionic will allow for the creation of a Vue project with Ionic Framework and any other dependencies. To create a new project, run the following command:

ionic start myApp blank --type vue
cd myApp

From here, we runionic serve and have our project running in the browser.

Build your way with TypeScript or JavaScript​

We love TypeScript at Ionic, and have believed for quite some time now that it’s a great tool for building scalable apps. That said, we know how much the Vue community values simplicity – in their tooling, languages, and more. In fact, it’s likely what drew you to Vue in the first place. Start simple – then scale up as needed.

So, if you’d prefer to use JavaScript instead of TypeScript, you can. After generating an Ionic Vue app, follow these steps:

1. Remove TypeScript dependencies:

npm uninstall --save typescript @types/jest @typescript-eslint/eslint-plugin @typescript-eslint/parser @vue/cli-plugin-typescript @vue/eslint-config-typescript

2. Change all.ts files to.js. In a blank Ionic Vue app, this should only besrc/router/index.ts andsrc/main.ts. If you're using tests, also change the extension of files in thetests directory.

3. Inindex.html, change the imported<script> file from/src/main.ts to/src/main.js.

4. Remove@vue/typescript/recommended and@typescript-eslint/no-explicit-any: ‘off’,from.eslintrc.js.

5. RemoveArray<RouteRecordRaw> and the import ofRouteRecordRaw fromsrc/router/index.js.

6. Delete thesrc/shims-vue.d.ts file if it exists. This is only needed when using the Vue CLI.

7. Removelang="ts" from thescript tags in any of your Vue components that have them. In a blank Ionic Vue app, this should only besrc/App.vue andsrc/views/HomePage.vue.

8. Delete thetsconfig.json file.

A look at a Vue Component​

The base of our app will be in thesrc directory, and the main entry point will be ourmain.ts file. If we open our project in a code editor and openmain.ts, we should see the following:

import{ createApp}from'vue';
import{ IonicVue}from'@ionic/vue';

import Appfrom'./App.vue';
import routerfrom'./router';

const app=createApp(App).use(IonicVue).use(router);

router.isReady().then(()=>{
  app.mount('#app');
});

So what is going on here? The first four lines are pulling in some dependencies. ThecreateApp function lets us initialize our Vue application, whileIonicVue is a plugin that allows us to use Ionic Framework in a Vue environment.

The third import is the root component for our app, simply namedApp. This is our first Vue component and will be used in the bootstrapping process for our Vue app.

The fourth import gets our routing configuration. We will look at this more in depth later.

If we openApp.vue we should see the following:

<template>
<ion-app>
<ion-router-outlet/>
</ion-app>
</template>

<scriptsetuplang="ts">
import{IonApp,IonRouterOutlet}from'@ionic/vue';
</script>

Let's break it down, starting with the imports.

<scriptsetuplang="ts">
  import {(IonApp, IonRouterOutlet)} from '@ionic/vue';
</script>

To use a component in Vue, you must first import it. So for Ionic Framework, this means anytime we want to use a Button or a Card, it must be added to our imports. In the case of ourApp component, we are usingIonApp andIonRouterOutlet. Vue'sscript setup syntax gives the template access to those components as<ion-app> and<ion-router-outlet>.

You can also register components globally if you find yourself importing the same components repeatedly. This comes with performance tradeoffs that we cover inOptimizing Your Build.

From there, let's look at the template.

<template>
<ion-app>
<ion-router-outlet/>
</ion-app>
</template>

All Vue components must have a<template>. Inside of there, we place ourIonApp andIonRouterOutlet components.

Initializing the router​

Ionic Vue uses thevue-router dependency, so if you are already familiar with Vue Router, you will be able to apply what you know to navigation in Ionic Vue. Let's take a look at the router configuration we mentioned before. Inrouter/index.ts, you should see something similar to the following:

import{ createRouter, createWebHistory}from'@ionic/vue-router';
import{RouteRecordRaw}from'vue-router';
importHomePagefrom'@/views/HomePage.vue';

const routes:Array<RouteRecordRaw>=[
{
    path:'/',
    redirect:'/home',
},
{
    path:'/home',
    name:'Home',
    component:HomePage,
},
];

const router=createRouter({
  history:createWebHistory(process.env.BASE_URL),
  routes,
});

exportdefault router;

The setup here is the same as if you were usingvue-router directly, but instead you need to import dependencies such ascreateRouter andcreateWebHistory from the@ionic/vue-router package.

After importing our dependencies, we can declare our routes in theroutes array. From there, we can create a router instance and provide it with our routes and the type of history we want to use.

With Ionic Vue, lazy loading works right out of the box. Instead of importing ourHome component, we could also do:

const routes:Array<RouteRecordRaw>=[
{
    path:'/',
    redirect:'/home',
},
{
    path:'/home',
    name:'Home',
component:()=>import('@/views/HomePage.vue'),
},
];

Now, you might be wondering: Why do we use@ when describing the path to our components? The@ symbol is a shortcut we can use to describe paths relative to thesrc directory. This is useful if we are trying to reference a component while in a file several folders deep. Instead of doing'../../../views/HomePage.vue', we could simply do'@/views/HomePage.vue'.

A component with style​

Now theApp component does not really have a lot to modify here. It is a basic example of a container component. With the router logic set, all it is responsible for is to render a component that matches the given URL route. Since we already have one component/router setup, let's go ahead and modify ourHome component.

Currently, theHome component looks like so:

<template>
<ion-page>
<ion-header:translucent="true">
<ion-toolbar>
<ion-title>Blank</ion-title>
</ion-toolbar>
</ion-header>

<ion-content:fullscreen="true">
<ion-headercollapse="condense">
<ion-toolbar>
<ion-titlesize="large">Blank</ion-title>
</ion-toolbar>
</ion-header>

<divid="container">
<strong>Ready to create an app?</strong>
<p>
          Start with Ionic
<atarget="_blank"rel="noopener noreferrer"href="https://ionicframework.com/docs/components"
>UI Components</a
>
</p>
</div>
</ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
import{IonContent,IonHeader,IonPage,IonTitle,IonToolbar}from'@ionic/vue';
</script>

<stylescoped>
#container{
text-align: center;

position: absolute;
left:0;
right:0;
top:50%;
transform:translateY(-50%);
}

#container strong{
font-size:20px;
line-height:26px;
}

#container p{
font-size:16px;
line-height:22px;

color:#8c8c8c;

margin:0;
}

#container a{
text-decoration: none;
}
</style>

Much like theApp component we started with, we have some imports for specific Ionic Framework components, an import from Vue, the Vue component, and styles to go along with our component.

For our styles, notice that we have specified our styles to bescoped. This means that the styles we write here will only apply to this component. This is useful for preventing styles from leaking out of a component and affecting other parts of your application. We strongly recommend usingscoped styles for Ionic Vue applications.

IonPage is the base component for all pages (a component with a route/URL), and includes some common building blocks of a full-screen component, like header, title, and content components.

IonHeader is a component meant to exist at the top of the page. It does not do much by itself, aside from handling some flexbox-based layout. It is meant to hold components, likeIonToolbar orIonSearchbar.

IonContent is, as its name suggests, the main content area for our page. It is responsible for providing a scrollable content that users will interact with, plus any scroll events that could be used in an app.

Our current content is relatively simple, but does not contain anything that could be used in a real app, so let's change that.

<template>
<ion-page>
    ...
<ion-content>
<ion-list>
<ion-item>
<ion-checkboxslot="start"></ion-checkbox>
<ion-label>
<h1>Create Idea</h1>
<ion-note>Run Idea By Brandy</ion-note>
</ion-label>
<ion-badgecolor="success"slot="end"> 5 Days</ion-badge>
</ion-item>
</ion-list>
</ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
import{
IonBadge,
IonCheckbox,
IonContent,
IonHeader,
IonItem,
IonLabel,
IonList,
IonNote,
IonPage,
IonTitle,
IonToolbar,
}from'@ionic/vue';
</script>

Here in ourIonContent, we are adding anIonList and a much more involvedIonItem component. Let's look atIonItem as it is the centerpiece here.

<ion-item>
<ion-checkboxslot="start"></ion-checkbox>
<ion-label>
<h1>Create Idea</h1>
<ion-note>Run Idea By Brandy</ion-note>
</ion-label>
<ion-badgecolor="success"slot="end"> 5 Days</ion-badge>
</ion-item>

Looking at our code, we have a special attribute called slot. This is key for letting theIonItem know where to place theIonCheckbox when it renders. This is not a Vue API, but a web standards API. Additionally, this is different from the slots API you may recall from Vue 2.

Let's look at another component from Ionic Framework, FAB. Floating Action Buttons are a nice way to provide a main action that is elevated from the rest of an app. For this FAB, we will need three components: a FAB, a FAB Button, and an Icon.

<template>
<ion-page>
<ion-content>
<ion-list> ...</ion-list>

<ion-fabvertical="bottom"horizontal="end"slot="fixed">
<ion-fab-button>
<ion-icon:icon="add"></ion-icon>
</ion-fab-button>
</ion-fab>
</ion-content>
</ion-page>
</template>

<scriptsetup>
import{
IonBadge,
IonCheckbox,
IonContent,
IonFab,
IonFabButton,
IonHeader,
IonIcon,
IonItem,
IonLabel,
IonList,
IonNote,
IonPage,
IonTitle,
IonToolbar,
}from'@ionic/vue';
import{ add}from'ionicons/icons';
</script>

On our mainIonFab, we are setting its positioning with the vertical and horizontal attributes. We are also setting the render location to "fixed" with the slot attribute. This will tellIonFab to render outside of the scrollable content inIonContent.

Now let's wire up a click handler to this. When clicking the FAB button, we want to navigate to a new page (which we will create in a moment). To do this, we will need to get access to Vue Router's navigation API. This can be done by importinguseRouter from thevue-router package.

<template>
<ion-page>
<ion-content>
<ion-list> ...</ion-list>

<ion-fabvertical="bottom"horizontal="end"slot="fixed">
<ion-fab-button@click="() => router.push('/new')">
<ion-icon:icon="add"></ion-icon>
</ion-fab-button>
</ion-fab>
</ion-content>
</ion-page>
</template>

<scriptsetup>
import{ add}from'ionicons/icons';
import{ useRouter}from'vue-router';
const router=useRouter();
</script>

In our component file, we are importing theuseRouter function. When called, this function injects the router dependency into the component. It gives us access to the history API from Vue Router, allowing us to push a new route onto the navigation stack. On ourIonFabButton, we can add a click handler, and just callrouter.push and pass in the new route. In this case, we will navigate tonew.

<ion-fab-button@click="() => router.push('/new')"> ...</ion-fab-button>

Creating a new Route​

Now that we have the pieces in place to navigate in our app, we need to create a new component and add the new route to our router declaration. Let's open ourrouter/index.ts file and add the new route.

import{ createRouter, createWebHistory}from'@ionic/vue-router';
import{RouteRecordRaw}from'vue-router';
importHomePagefrom'@/views/HomePage.vue';
importNewItemfrom'@/views/NewItem.vue';

const routes:Array<RouteRecordRaw>=[
{
    path:'/',
    redirect:'/home',
},
{
    path:'/home',
    name:'Home',
    component:HomePage,
},
{
    path:'/new',
    name:'NewItem',
    component:NewItem,
},
];

const router=createRouter({
  history:createWebHistory(process.env.BASE_URL),
  routes,
});

exportdefault router;

With our router now having an entry for the route/new, we will create the component needed,NewItem. This will exist inviews/NewItem.vue.

Let's fill theNewItem.vue file with some placeholder content for the moment.

<template>
<ion-page>
<ion-header>
<ion-toolbar>
<ion-buttonsslot="start">
<ion-back-button></ion-back-button>
</ion-buttons>
<ion-title>New Item</ion-title>
</ion-toolbar>
</ion-header>
<ion-content></ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
import{IonBackButton,IonButtons,IonContent,IonHeader,IonPage,IonTitle,IonToolbar}from'@ionic/vue';
</script>

The content here should look similar to theHome component. What is different here is theIonBackButton component. This is used to navigate back to the previous route. Seems easy enough, right? Ok, but what if we reload the page?

In this case, the in-memory history is lost, so the back button disappears. To address this, we can set thedefault-href attribute value to the URL we want to navigate to if there is no history.

<ion-back-buttondefault-href="/home"></ion-back-button>

Now, If there is no app history present, we will be able to navigate back to our home route.

Calling Methods on Components​

In order to call a method on any of the Ionic Vue components, you will first need to get a reference to the component instance. Next, you will need to access the underlying Web Component using$el and call the method.

In other framework integrations such as Ionic React, this is not needed as anyref you provide is automatically forwarded to the underlying Web Component instance. We are unable to do the same thing here due to limitations in how Vue manages refs.

<template>
<ion-contentref="content">
<ion-button@click="scrollToBottom">Scroll to Bottom</ion-button>

    ...
</ion-content>
</template>

<scriptsetuplang="ts">
import{IonButton,IonContent}from'@ionic/vue';
import{ ref}from'vue';

const content=ref();
constscrollToBottom=()=>{
    content.value.$el.scrollToBottom(300);
};
</script>

Adding Icons​

Ionic Vue comes withIonicons pre-installed. There are a couple options developers have for using them in their application.

Per-Component Imports​

Per-Component Imports is the recommended approach to using Ionicons. This involves importing the icon of your choice from theionicons package and passing it to your template:

<template>
<ion-page>
<ion-content>
<ion-icon:icon="heart"></ion-icon>
</ion-content>
</ion-page>
</template>

<scriptsetup>
import{ heart}from'ionicons/icons';
import{IonContent,IonIcon,IonPage}from'@ionic/vue';
</script>

Let's break down what we are doing here. First, we are importing theheart icon fromionicons/icons. This will load the appropriate SVG data for our icon.

Then we pass the icon data into theion-icon component via theicon property.

Developers also have the option of setting different icons based upon the mode:

<template>
<ion-page>
<ion-content>
<ion-icon:ios="logoApple":md="logoAndroid"></ion-icon>
</ion-content>
</ion-page>
</template>

<scriptsetup>
import{ logoAndroid, logoApple}from'ionicons/icons';
import{IonContent,IonIcon,IonPage}from'@ionic/vue';
</script>

Note that any icon names that are hyphenated should be written in camel case when importing.

Global Imports​

The other option is to import specific icons globally. This is not typically recommended as it will force icons to be loaded every time your application starts and can increase your application's initial chunk size.

That being said, there may be use cases when it makes sense to load specific icons globally:

main.ts

import{ addIcons}from'ionicons';
import{ heart}from'ionicons/icons';

addIcons({
  heart: heart,
});

HomePage.vue

<template>
<ion-page>
<ion-content>
<ion-iconicon="heart"></ion-icon>
</ion-content>
</ion-page>
</template>

<scriptsetup>
import{IonContent,IonIcon,IonPage}from'@ionic/vue';
</script>

Inmain.ts, theaddIcons function lets us register icons globally and give it a string as a key. We then reference the icon by that key in ourHome component.

Optimizing Your Build​

Vue gives you several tools to fine tune your application. This section will cover the options that are most relevant to Ionic Framework.

Local Component Registration (Recommended)​

By default, Ionic Framework components are registered locally. With local registration, these components are imported and provided to each Vue component you want to use them in. This is the recommended approach as it allows lazy loading and treeshaking to work properly with Ionic Framework components.

The one downside to this approach is that it may be tedious to re-import your Ionic Framework components multiple times. However, we feel that the performance benefits you receive in exchange are worth it.

Also note that locally registered components are not available in subcomponents. You will need to re-import the Ionic Framework components you would like to use in your subcomponent.

Let's take a look at how local component registration works:

<template>
<ion-page>
<ion-content>
<SubComponent></SubComponent>
</ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
import{IonContent,IonPage}from'@ionic/vue';
importSubComponentfrom'@/components/SubComponent.vue';
</script>

In the example above, we are using theIonPage andIonContent components. To use them, we import them from@ionic/vue. From there, we can use the components in our template.

Note that since we are registering these components locally, neitherIonPage norIonContent will be available inSubComponent unless we register them there as well.

For more information, see theLocal Registration Vue Documentation.

Global Component Registration​

The other option for registering components is to use global registration. Global registration involves importing the components you want to use inmain.ts and calling thecomponent method on your Vue app instance.

While this makes it easier to add Ionic Framework components to your Vue app, global registration often is not ideal. To quote the Vue documentation: "If you're using a build system like Webpack, globally registering all components means that even if you stop using a component, it could still be included in your final build. This unnecessarily increases the amount of JavaScript your users have to download".

Let's take a look at how global component registration works:

main.ts

import{IonContent,IonicVue,IonPage}from'@ionic/vue';

const app=createApp(App).use(IonicVue).use(router);

app.component('ion-content',IonContent);
app.component('ion-page',IonPage);

MyComponent.vue

<template>
<ion-page>
<ion-content>
<SubComponent></SubComponent>
</ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
importSubComponentfrom'@/components/SubComponent.vue';
</script>

In the example above, we are using theIonPage andIonContent components. To use them, we first import them from@ionic/vue inmain.ts. From there, we call thecomponent method on our app instance and pass it the tag name as well as the component definition. After we do that, we can use the components in the rest of our application without having to import them into each Vue component.

For more information, see theGlobal Registration Vue Documentation.

Prefetching Application JavaScript​

By default, the Vue CLI will automatically generate prefetch hints for the JavaScript in your application. Prefetching utilizes the browser idle time to download documents that the user might visit in the near future. When the user visits a page that requires the prefetched document, it can be served quickly from the browser's cache.

Prefetching consumes bandwidth, so if you have a large app, you may want to disable it. You can do this by modifying or creating yourvue.config.js file:

vue.config.js

module.exports={
chainWebpack:(config)=>{
    config.plugins.delete('prefetch');
},
};

The configuration above will prevent all files from being prefetched and, instead, will be loaded when they are needed. You can also select certain chunks to prefetch. Check out theVue CLI Docs on Prefetching for more examples.

Build a Native App​

We now have the basics of an Ionic Vue app down, including some UI components and navigation. The great thing about Ionic Framework’s components is that they work anywhere, including iOS, Android, and PWAs. To deploy to mobile, desktop, and beyond, we use Ionic’s cross-platform app runtimeCapacitor. It provides a consistent, web-focused set of APIs that enable an app to stay as close to web-standards as possible while accessing rich native device features on platforms that support them.

Adding native functionality is easy. First, add Capacitor to your project:

ionic integrations enable capacitor

Next, build the project, then add your platform of choice:

ionic build
ionic cap add ios
ionic cap add android

We use the standard native IDEs (Xcode and Android Studio) to open, build, and run the iOS and Android projects:

ionic cap open ios
ionic cap open android

Additional details can be foundhere.

Next, check outall the APIs that are available. There is some great features, including theCamera API. We can implement photo capture functionality in just a few lines of code:

<template>
<ion-page>
<ion-header>
<ion-toolbar>
<ion-title>Ionic Blank</ion-title>
</ion-toolbar>
</ion-header>
<ion-contentclass="ion-padding">
<img:src="imageSrc"/>
<ion-button@click="takePhoto()">Take Photo</ion-button>
</ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
import{IonButton,IonContent,IonHeader,IonPage,IonTitle}from'@ionic/vue';
import{ ref}from'vue';
import{Camera,CameraResultType}from'@capacitor/camera';

const imageSrc=ref('');
consttakePhoto=async()=>{
const image=awaitCamera.getPhoto({
quality:90,
allowEditing:true,
resultType:CameraResultType.Uri,
});

    imageSrc.value= image.webPath;
};
</script>

Where to go from here​

This guide covered the basics of creating an Ionic Vue app, adding some basic navigation, and introducing Capacitor as a way of building native apps. To dive deeper into building complete Ionic Framework apps with Vue and Capacitor, follow ourFirst App guide.

For a more detailed look at Ionic Frameworks’s components, check out thecomponent API pages. For more details on Vue, review theVue Docs. To keep building native features, see theCapacitor docs.

Happy app building! 🎉

• What is Ionic Framework?
• Creating a project with the Ionic CLI
• Build your way with TypeScript or JavaScript
• A look at a Vue Component
• Initializing the router
• A component with style
• Creating a new Route
• Calling Methods on Components
• Adding Icons
  • Per-Component Imports
  • Global Imports
• Optimizing Your Build
  • Local Component Registration (Recommended)
  • Global Component Registration
  • Prefetching Application JavaScript
• Build a Native App
• Where to go from here