Routing within your Nuxt Ionic application will feel very similar, but with a couple of differences.

By default, this module sets up the Ionic Router, or IonRouter. This router is built on top of vue-router, but with some changed functionality specifically for making it work better for mobile applications.

  • Enables non-linear routing, e.g. for application tabs
  • Separate navigation stacks for each tab of your application
  • Rich page transitions out-of-the-box, appropriate for mobile
  • Simple API for custom animations and direction control when navigating via links


Just like regular Nuxt, you can start building your Ionic application by creating routes within the ~/pages directory. Every Vue file inside this directory will generate a route that displays the contents of the file. Read more about Nuxt file-based routing here.

  • The root component of every page must always be the <ion-page> component.

This is required by Ionic to set up page transitions and stack navigation. Each view that is navigated to using the router must include an <ion-page> component.

<template>  <ion-page>    <ion-header>      <ion-toolbar>        <ion-title>Home</ion-title>      </ion-toolbar>    </ion-header>    <ion-content class="ion-padding">Hello World</ion-content>  </ion-page></template>
Read more about <ion-page> here.

Defining page meta

Nuxt utilities like definePageMeta are fully functional. However, you should avoid using <NuxtPage> or <NuxtLayout> as these will not function correctly, due to Ionic requiring an <ion-router-outlet> instead.

Read more about definePageMeta here.

Define a root alias if there's no index.vue page

Usually applications with tab bars will not have a ~/pages/index.vue file, as it's not needed. However, this will mean opening the app will return a 404, e.g. on localhost:3000.

To solve this, 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: ['/'],})

It will now be used as the root path, and will be routed to by default when visiting e.g. localhost:3000.

Navigation can be done in several ways, using the IonRouter or certain ion- components.

Read about navigation in Ionic's Vue Navigation docs.


To access the router, use the composable useIonRouter(). This should always be used instead of the regular useRouter() (which is auto-imported from vue-router by Nuxt). This ensures the benefits of the Ion Router are always provided.

This module auto-imports useIonRouter() so it should be available automatically. If this is disabled, you can import it from @ionic/vue.

It is best used when you wish to control navigation programmatically and have full control over the page transitions.

<script setup lang="ts">import { customAnimation } from '~/animations/customAnimation';const router = useIonRouter();const goHome = () => router.push('/home');const goBack = () => router.back();const replaceRoute = () => router.replace({ name: 'newRoute' })const customAnimatedNavigation = () => router.navigate('/page2', 'forward', 'replace', customAnimation);</script>
Read more about useIonRouter() here.

All Ionic components expose a router-link attribute. When set, the router will navigate to the specified route when the component is clicked. It accepts strings as well as named routes.

router-direction and router-animation are also available for further control.

It's best used when simple routing is required, without any programmatic logic before or after.

<template>  <ion-button router-link="{ name: 'myPage' }">Click Me</ion-button>  <ion-button     router-link="/page2"     router-direction="back"     :router-animation="myAnimation"  >    Click Me  </ion-button></template>
Avoid using <NuxtLink> for now as it currently is not integrated with the Ionic Router.

Route Parameters

When accessing route parameters, useRoute() should continue to be used, just like regular Nuxt.

<script setup lang="ts">const route = useRoute()// When accessing /posts/1, will be 1console.log(</script>
Read more about Nuxt route parmeters here.

Route Middleware

Nuxt's Route Middleware is also integrated and available, just like regular Nuxt.

export default defineNuxtRouteMiddleware((to, from) => {  // isAuthenticated() is an example method verifying if a user is authenticated  if (isAuthenticated() === false) {    return showLoginModal(); // showLoginModal() is an example of opening a modal flow for authentication  }})
<script setup lang="ts">definePageMeta({  middleware: 'auth'})</script><template>  <h1>Welcome to your feed</h1></template>