Routing

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.

Pages

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.

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>

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.

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

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

IonRouter

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>

Navigating with Components

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>

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, route.params.id will be 1
console.log(route.params.id)
</script>

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>