If you're looking for a high-level overview of what Ionic Vue is and how it fits into the Vue ecosystem, see theIonic Vue Overview.

Prerequisites​

Before you begin, make sure you have Node.js and npm installed on your machine.You can check by running:

node -v
npm -v

If you don't have Node.js and npm,download Node.js here (which includes npm).

Create a Project with the Ionic CLI​

First, install the latestIonic CLI:

npm install -g @ionic/cli

Then, run the following commands to create and run a new project:

ionic start myApp blank --type vue

cd myApp
ionic serve

After runningionic serve, your project will open in the browser.

Explore the Project Structure​

Your new app'ssrc directory will look like this:

├── App.vue
├── main.ts
├── router
│   └── index.ts
└── views
    └── HomePage.vue

Let's walk through these files to understand the app's structure.

View the App Component​

The root of your app is defined inApp.vue:

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

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

This sets up the root of your application, using Ionic'sion-app andion-router-outlet components. The router outlet is where your pages will be displayed.

View Routes​

Routes are defined inrouter/index.ts:

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

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

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

exportdefault router;

When you visit the root URL (/), theHomePage component will be loaded.

View the Home Page​

The Home page component, defined inviews/HomePage.vue, imports the Ionic components and defines the page template:

<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>

<!-- ...styles... -->

This creates a page with a header and scrollable content area. The second header shows acollapsible large title that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.

Add an Ionic Component​

You can enhance your Home page with more Ionic UI components. For example, add aButton at the end of theion-content:

<ion-content>
<!-- existing content -->

<ion-button>Navigate</ion-button>
</ion-content>

Then, import theIonButton component in the<script> tag:

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

Add a New Page​

Create a new page atviews/NewPage.vue:

<template>
<ion-page>
<ion-header:translucent="true">
<ion-toolbar>
<ion-buttonsslot="start">
<ion-back-buttondefault-href="/"></ion-back-button>
</ion-buttons>
<ion-title>New</ion-title>
</ion-toolbar>
</ion-header>

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

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

This creates a page with aBack Button in theToolbar. The back button will automatically handle navigation back to the previous page, or to/ if there is no history.

Navigate to the New Page​

To navigate to the new page, create a route for it by first importing it at the top ofrouter/index.ts after theHomePage import:

To navigate to a new page, add the route torouter/index.ts

importNewPagefrom'../views/NewPage.vue';

Then, add its route in theroutes array:

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

Once that is done, update the button inviews/HomePage.vue:

<ion-buttonrouter-link="/new">Navigate</ion-button>

Add Icons to the New Page​

Ionic Vue comes withIonicons pre-installed. You can use any icon by setting theicon property of theion-icon component.

Update the imports inviews/NewPage.vue to importIonIcon and theheart andlogoIonic icons:

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

Then, include them inside of theion-content:

<ion-icon:icon="heart"></ion-icon>
<ion-icon:icon="logoIonic"></ion-icon>

Note that we are passing the imported SVG reference,not the icon name as a string.

For more information, see theIcon documentation and theIonicons documentation.

Call Component Methods​

Let's add a button that can scroll the content area to the bottom.

Updateviews/NewPage.vue to include a ref onion-content and a button and some items after the existing icons:

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

<!-- Add lots of content to make scrolling possible -->
<ion-itemv-for="i in 50":key="i">
<ion-label>Item {{ i }}</ion-label>
</ion-item>
</ion-content>

In the script section, add the new component imports and define thescrollToBottom function:

<scriptsetuplang="ts">
import{
IonBackButton,
IonButtons,
IonButton,
IonContent,
IonHeader,
IonIcon,
IonItem,
IonLabel,
IonPage,
IonTitle,
IonToolbar,
}from'@ionic/vue';
import{ heart, logoIonic}from'ionicons/icons';
import{ ref}from'vue';

const content=ref();

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

To call methods on Ionic components:

1. Create aref for the component
2. Access the underlying Web Component via$el
3. Call the method on the Web Component

This pattern is necessary because Ionic components are built as Web Components. The$el property gives you access to the actual Web Component instance where the methods are defined.

You can find available methods for each component in theMethods section of their API documentation.

Run on a Device​

Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, useCapacitor:

ionic build
ionic cap add ios
ionic cap add android

Open the native projects in their IDEs:

ionic cap open ios
ionic cap open android

SeeCapacitor's Getting Started guide for more.

Build with TypeScript or JavaScript​

Ionic Vue projects are created with TypeScript by default, but you can easily convert to JavaScript if you prefer. After generating a blank Ionic Vue app, follow these steps:

1. Remove the TypeScript dependencies:

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

2. Change the extension of all.ts files to.js. In a blank Ionic Vue app, this will be therouter/index.ts,main.ts, and 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 fromrouter/index.js.

6. Removelang="ts" from thescript tags in any of your Vue components that have them. In a blank Ionic Vue app, this should only beApp.vue andviews/HomePage.vue.

7. Deletetsconfig.json andvite-env.d.ts.

8. In package.json, change the build script from"build": "vue-tsc && vite build" to"build": "vite build".

9. Install tersernpm i -D terser.

Explore More​

This guide covered the basics of creating an Ionic Vue app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:

Build Your First App

Build a real Photo Gallery app with Ionic Vue and native device features.

Vue Documentation

Learn more about Vue's core concepts, tools, and best practices from the official Vue documentation.

Navigation

Discover how to handle routing and navigation in Ionic Vue apps using the Vue Router.

Components

Explore Ionic's rich library of UI components for building beautiful apps.

Theming

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

Capacitor Documentation

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.

• Prerequisites
• Create a Project with the Ionic CLI
• Explore the Project Structure
• View the App Component
• View Routes
• View the Home Page
• Add an Ionic Component
• Add a New Page
• Navigate to the New Page
• Add Icons to the New Page
• Call Component Methods
• Run on a Device
• Build with TypeScript or JavaScript
• Explore More