Routing

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

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.

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

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>