Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Navigation and Routing

Ionic Routing Basics and ion-router-outlet

Learn how Ionic routing keeps a stack of pages, how ion-router-outlet differs from a plain router, and how to set routes, links and back navigation.

Websites replace one page with another. Mobile apps stack pages: opening a detail page puts it on top, the back gesture takes it off, and the page below is still there exactly as you left it. Ionic's routing is built around this idea. This lesson explains the stack model, shows routes in all three flavours, and covers links, redirects and the back button.

The stack model

flowchart LR
  A["Home"] -->|push| B["Details"]
  B -->|push| C["Edit"]
  C -->|pop| B
  B -->|pop| A

Each push adds a page on top of the stack; each pop removes the top page and reveals the one below.

The key difference from a normal single-page app: pages stay alive in the DOM while others are on top of them. When you go back, the previous page is shown again with its scroll position and form values intact, and it is not rebuilt. This is what makes mobile transitions feel native, and it also explains some lifecycle behaviour in route params, guards and lifecycle.

ion-router-outlet is the component that holds the stack. It animates transitions between pages (a slide on iOS, a fade-up on Android).

Defining routes

Angular uses the standard Angular Router with ion-router-outlet in the root template:

TypeScript
// app.routes.ts
import { Routes } from '@angular/router';

export const routes: Routes = [
  { path: '', redirectTo: 'home', pathMatch: 'full' },
  { path: 'home', loadComponent: () => import('./home/home.page').then((m) => m.HomePage) },
  { path: 'details/:id', loadComponent: () => import('./details/details.page').then((m) => m.DetailsPage) },
];
HTML
<!-- app.component.html -->
<ion-app>
  <ion-router-outlet></ion-router-outlet>
</ion-app>

React wraps React Router v5 in IonReactRouter:

JSX
import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
import { Redirect, Route } from 'react-router-dom';

setupIonicReact();

const App = () => (
  <IonApp>
    <IonReactRouter>
      <IonRouterOutlet>
        <Route exact path="/home" component={Home} />
        <Route exact path="/details/:id" component={Details} />
        <Route exact path="/"><Redirect to="/home" /></Route>
      </IonRouterOutlet>
    </IonReactRouter>
  </IonApp>
);

Vue uses Vue Router 4 with createWebHistory:

TypeScript
import { createRouter, createWebHistory } from '@ionic/vue-router';

const routes = [
  { path: '/', redirect: '/home' },
  { path: '/home', component: () => import('../views/HomePage.vue') },
  { path: '/details/:id', component: () => import('../views/DetailsPage.vue') },
];

export default createRouter({ history: createWebHistory(import.meta.env.BASE_URL), routes });
HTML
<ion-app><ion-router-outlet /></ion-app>

Always import createRouter from @ionic/vue-router, not from vue-router. Ionic's version adds stack handling. In React, always put routes directly inside IonRouterOutlet, and add exact.

HTML
<!-- Angular, declarative -->
<ion-button routerLink="/details/42">Open</ion-button>
<ion-button routerLink="/home" routerDirection="root">Go home</ion-button>
TypeScript
// Angular, code
import { NavController } from '@ionic/angular/standalone';
constructor(private nav: NavController) {}
open() { this.nav.navigateForward('/details/42'); }
JSX
// React
const history = useHistory();
history.push('/details/42');
// or: <IonButton routerLink="/details/42">Open</IonButton>
TypeScript
// Vue
const router = useIonRouter();
router.push('/details/42');

The direction controls the animation: forward (push), back (pop) or root (replace the stack, no back button). Use root when going from login to home, so the back gesture does not return to login.

The back button

HTML
<ion-header>
  <ion-toolbar>
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/home"></ion-back-button>
    </ion-buttons>
    <ion-title>Details</ion-title>
  </ion-toolbar>
</ion-header>

ion-back-button appears only when there is a page to go back to. defaultHref is where it goes when the page was opened directly (a deep link or a page refresh), because then the stack is empty. Always set it. The Android hardware back button and the iOS swipe-back gesture are handled for you.

Stand-in: a navigation stack

The stack is simply an array with push, pop and replace. This stand-in models it including the "no history" case that defaultHref handles. It is plain JavaScript, not Ionic's router.

JS Stand-in: push, pop and root navigation

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Redirects, wildcards and 404

Define a catch-all so unknown URLs do not give a blank page:

TypeScript
{ path: '**', redirectTo: 'home' }          // Angular
JSX
<Route><Redirect to="/home" /></Route>      {/* React: last, without a path */}
TypeScript
{ path: '/:pathMatch(.*)*', redirect: '/home' } // Vue

For a real "not found" page, point the wildcard at a component instead of redirecting, and keep the same layout.

Because the app is a single-page app, the URL stays in sync, so a link such as https://app.example.com/details/42 opens the right page on the web. On devices, Capacitor can register universal links and app links that open the app at that route, which you will do in chapter 5. Design your URLs so every screen can be opened directly, and handle missing data gracefully.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is different about Ionic's page stack compared with a normal single-page app?

    Ionic keeps previous pages alive so going back restores scroll position and state.
  2. 2. When is routerDirection="root" useful?

    Root replaces the stack and resets history.
  3. 3. Why set defaultHref on ion-back-button?

    After a refresh or deep link there is nothing to go back to, so defaultHref supplies a destination.
  4. 4. In Ionic Vue, where should createRouter be imported from?

    The Ionic version of createRouter adds the stack navigation behaviour.

Summary

  • Ionic navigation is a stack: push adds, pop removes, root replaces.
  • ion-router-outlet holds and animates pages; lower pages stay alive.
  • Routes are defined with the framework's router (Angular Router, React Router v5, Vue Router with Ionic's wrapper).
  • Use ion-back-button with defaultHref, and root direction after login.
  • Add a wildcard route for unknown URLs.

Next: Tab Navigation