Page routing

Out of the box, you can start building your Ionic application by creating routes within ~/pages directory. To access the router, you should use useIonRouter() rather than useRouter() (which is auto-imported from vue-router).

Nuxt utilities like definePageMeta will continue to work, but you should avoid using <NuxtPage> or <NuxtLayout>.

The root component of every page should be the <ion-page> component.
If you do not have a ~/pages/index.vue file in your project, you should add the following code to the page that you want to be displayed on your app's root page:
definePageMeta({  alias: ['/'],})

Theming the app

To customize the theme of your app, you can override the Ionic's default css variables. You can start by creating a ~/assets/css/ionic.css file and adding it to css property in your nuxt.config.ts file. Following the example:

export default defineNuxtConfig({  css: ['~/assets/css/ionic.css'],})
:root {  --ion-color-primary: #57e389;  --ion-color-primary-rgb: 87, 227, 137;  --ion-color-primary-contrast: #000000;  --ion-color-primary-contrast-rgb: 0, 0, 0;  --ion-color-primary-shade: #4dc879;  --ion-color-primary-tint: #68e695;  /* And so on... */}

To learn more about theming and which variables to override, check out Ionic's official theming documentation.

Ionic Framework components

All Ionic Vue components should be auto-imported throughout your app. (If you find one that isn't, please open an issue.) Although your IDE should be aware of these everywhere, they are not globally registered and are only imported within the components that use them. For more on how component imports work, see the Nuxt documentation.

If you find a component that isn't being auto-imported, please open an issue or a pull request. If you're thinking of latter option, please do so in alphabetical order for making it easy for others to find the component as well!

Module utility components

Module also offers few components made for easier and more seamless way to integrate Ionic's composables or functions into your Nuxt app.

IonAnimation component

Component made specifically to make usage of Ionic's createAnimation easier. It has almost 1 to 1 props matching as your usual animation object. For more see official Ionic docs or check out playground examples

You can see how it replaces usage of regular createAnimation function in the code example below:

<template>  <IonAnimation    :duration="3000"    :iterations="Infinity"    :keyframes="[      { offset: 0, background: 'red' },      { offset: 0.72, background: 'var(--background)' },      { offset: 1, background: 'green' },    ]"    playOnMount  >    <!-- Content to animate -->  </IonAnimation></template>
Manual usage
<script setup lang="ts">// Template ref of your elementconst squareRef = ref()// Your animation objectconst animation = createAnimation()  .addElement(squareRef.value)  .duration(3000)  .iterations(Infinity)  .keyframes([    { offset: 0, background: 'red' },    { offset: 0.72, background: 'var(--background)' },    { offset: 1, background: 'green' },  ])onMounted(() => {})</script>
Currently component doesn't support grouped and chained animations. For that usage we still recommend using createAnimation by itself


Icons are auto-imported from ionicons/icons by default, following the pattern of camel case naming with ionicons in front of the original icon name, that you can find on the official ionicons website.

Auto-imported icons
<template>  <ion-icon :icon="ioniconsImage"></ion-icon>  <ion-icon :md="ioniconsSquareSharp" :ios="ioniconsTriangleOutline"></ion-icon></template>
Manual imports
<script setup lang="ts">import { image, squareSharp, triangleOutline } from 'ionicons/icons'</script><template>  <ion-icon :icon="image"></ion-icon>  <ion-icon :md="squareSharp" :ios="triangleOutline"></ion-icon></template>

You can opt-out of auto-importing by setting integrations.icons module options in your nuxt.config.ts to false.

Helper functions

Nuxt provides a number of Ionic hooks/composables via auto-imports within your app:

createAnimation, createGesture, getPlatforms, getTimeGivenProgression, iosTransitionAnimation, isPlatform, mdTransitionAnimation, menuController, onIonViewWillEnter, onIonViewDidEnter, onIonViewWillLeave, onIonViewDidLeave, useBackButton, useKeyboard, useIonRouter

For more on what these do, you can read the Ionic docs. For more on how auto-imports work, see the Nuxt documentation.


Customizing your root app.vue

If you need to customize the default Ionic app.vue file, you can create a new one in your project's source directory.

This is the default:

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