In this article we going to learn how to handle the Android back button in an Ionic Capacitor app so we can control exactly what happens when users press it — instead of letting the default behaviour close the app at the wrong moment.
The Android back button is something iOS developers never think about, but on Android it's a critical part of the user experience. Users expect it to work a certain way — go back in navigation, close a modal, dismiss a dialog. When it doesn't behave as expected, users get frustrated or accidentally exit the app.
By default in Ionic, the back button works for basic navigation. But it breaks down in specific situations — like when we have a custom modal open, when we're on the root page and want to show an "exit app" confirmation, or when we have a side menu open that should close first before navigating back. We have to handle these cases ourselves.
This tutorial shows how to:
- Understand how Ionic handles the Android back button
- Listen to back button events using Platform service
- Show an exit confirmation when pressing back on the root page
- Close a modal or popover when back button is pressed
- Handle back button in specific pages differently
- Manage back button priority when multiple listeners are active
- Handle the hardware back button with Capacitor's App plugin
Why We Need Custom Back Button Handling
Ionic's router handles basic back navigation automatically. Press back, go to the previous page. That works fine for simple apps.
But these scenarios break without custom handling :
Root page exit — user is on the home page, presses back, app exits immediately. No confirmation. Users accidentally exit all the time. We should ask "Are you sure you want to exit?"
Modal open — user opens a modal, presses back, app navigates to the previous page instead of closing the modal. Wrong behaviour.
Side menu open — user opens the side menu, presses back, app goes back instead of closing the menu.
Custom drawer or bottom sheet — any custom overlay that isn't an Ionic modal needs its own back button handling.
Prevent back on certain pages — payment screen, form with unsaved data — we might want to prevent accidental back navigation.
Step 1 : Listen to Back Button Using Platform Service
Ionic provides a Platform service with a backButton observable. This is the starting point for all back button handling.
import { Component, OnInit, OnDestroy } from '@angular/core';
import { Platform } from '@ionic/angular';
import { Subscription } from 'rxjs';
@Component({
selector: 'app-root',
template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`
})
export class AppComponent implements OnInit, OnDestroy {
private backButtonSub!: Subscription;
constructor(private platform: Platform) {}
ngOnInit() {
this.backButtonSub = this.platform.backButton.subscribeWithPriority(10, () => {
console.log('Back button pressed');
});
}
ngOnDestroy() {
this.backButtonSub.unsubscribe();
}
}
subscribeWithPriority(priority, handler) — the priority number controls which handler runs when multiple listeners are registered. Higher number wins. If we have a modal listener at priority 20 and a page listener at priority 10, the modal handler runs and the page handler is ignored.
Default Ionic back button priority is 0 for the router. So anything we register at priority 10 or higher overrides the default routing behaviour.
Step 2 : Exit App Confirmation on Root Page
The most common use case — show an "Are you sure you want to exit?" alert when the user presses back on the root/home page.
The best place to set this up is in app.component.ts so it applies globally :
import { Component, OnInit } from '@angular/core';
import { Platform, AlertController, NavController } from '@ionic/angular';
import { Location } from '@angular/common';
@Component({
selector: 'app-root',
template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`
})
export class AppComponent implements OnInit {
constructor(
private platform: Platform,
private alertController: AlertController,
private location: Location,
private navController: NavController
) {}
ngOnInit() {
this.initBackButton();
}
private initBackButton() {
this.platform.backButton.subscribeWithPriority(10, async () => {
// Check if we can go back in navigation history
if (window.history.length > 1) {
this.location.back();
} else {
// We're at the root — show exit confirmation
await this.showExitConfirm();
}
});
}
private async showExitConfirm() {
const alert = await this.alertController.create({
header: 'Exit App',
message: 'Are you sure you want to exit?',
buttons: [
{
text: 'Cancel',
role: 'cancel'
},
{
text: 'Exit',
handler: () => {
// Exit the app
(navigator as any).app?.exitApp();
}
}
]
});
await alert.present();
}
}
(navigator as any).app?.exitApp() calls the Cordova/Capacitor exit method. For Capacitor apps there's a cleaner way using the App plugin — we'll show that in Step 6.
window.history.length > 1 checks if there are pages to go back to. On the first page the history length is 1 (only the current page). If it's more than 1, we go back normally. If it's 1, we show the exit prompt.
Step 3 : Close Modal on Back Button Press
When we have an Ionic modal open, pressing back should close it — not navigate away. The modal needs its own back button listener with higher priority than the global one.
Here's how to handle it inside the modal component :
import { Component, OnInit, OnDestroy } from '@angular/core';
import { ModalController, Platform } from '@ionic/angular';
import { Subscription } from 'rxjs';
@Component({
selector: 'app-my-modal',
standalone: true,
template: `
<ion-header>
<ion-toolbar>
<ion-title>My Modal</ion-title>
<ion-buttons slot="end">
<ion-button (click)="closeModal()">Close</ion-button>
</ion-buttons>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<p>Modal content here</p>
</ion-content>
`
})
export class MyModalComponent implements OnInit, OnDestroy {
private backButtonSub!: Subscription;
constructor(
private modalController: ModalController,
private platform: Platform
) {}
ngOnInit() {
// Higher priority than the global handler (10)
this.backButtonSub = this.platform.backButton.subscribeWithPriority(20, async () => {
await this.closeModal();
});
}
ngOnDestroy() {
this.backButtonSub.unsubscribe();
}
async closeModal() {
await this.modalController.dismiss();
}
}
Priority 20 overrides our global handler at priority 10. When the modal is open, pressing back calls modalController.dismiss(). When the modal is dismissed, the listener is unsubscribed in ngOnDestroy, so the global handler takes over again.
This pattern works for popovers, action sheets, and any other overlay component — register a high-priority listener when it opens, unsubscribe when it closes.
Step 4 : Close Side Menu on Back Button
If we have an ion-menu (side drawer), pressing back should close it before navigating away.
import { Component, OnInit } from '@angular/core';
import { Platform, MenuController } from '@ionic/angular';
import { Location } from '@angular/common';
@Component({
selector: 'app-root',
template: `
<ion-app>
<ion-menu contentId="main-content">
<ion-header>
<ion-toolbar><ion-title>Menu</ion-title></ion-toolbar>
</ion-header>
<ion-content>
<!-- menu items -->
</ion-content>
</ion-menu>
<ion-router-outlet id="main-content"></ion-router-outlet>
</ion-app>
`
})
export class AppComponent implements OnInit {
constructor(
private platform: Platform,
private menuController: MenuController,
private location: Location
) {}
ngOnInit() {
this.platform.backButton.subscribeWithPriority(10, async () => {
// Check if menu is open first
const menuOpen = await this.menuController.isOpen();
if (menuOpen) {
await this.menuController.close();
return; // Don't navigate back — just close the menu
}
// Menu is not open — handle normal back navigation
if (window.history.length > 1) {
this.location.back();
} else {
await this.showExitConfirm();
}
});
}
}
We check menuController.isOpen() first. If the menu is open, we close it and return early. If not, we proceed with normal back navigation logic. The user has to press back twice to exit — once to close the menu, once more to trigger the exit confirmation.
Step 5 : Prevent Back Navigation on Specific Pages
Sometimes we don't want the user to go back at all — like a payment processing screen or a form with unsaved changes.
Create a guard or handle it directly in the page component :
import { Component, OnInit, OnDestroy } from '@angular/core';
import { Platform, AlertController } from '@ionic/angular';
import { Subscription } from 'rxjs';
@Component({
selector: 'app-payment',
standalone: true,
template: `
<ion-header>
<ion-toolbar>
<ion-title>Processing Payment</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<p>Please wait while we process your payment...</p>
</ion-content>
`
})
export class PaymentPage implements OnInit, OnDestroy {
private backButtonSub!: Subscription;
isProcessing = true;
constructor(
private platform: Platform,
private alertController: AlertController
) {}
ngOnInit() {
this.backButtonSub = this.platform.backButton.subscribeWithPriority(20, async () => {
if (this.isProcessing) {
// Show warning — don't go back during payment
const alert = await this.alertController.create({
header: 'Payment in Progress',
message: 'Please do not go back while payment is processing.',
buttons: ['OK']
});
await alert.present();
}
// If not processing, do nothing — just consume the back button event
});
}
ngOnDestroy() {
this.backButtonSub.unsubscribe();
}
}
By registering a higher-priority listener that doesn't navigate, we effectively block back navigation. The listener "consumes" the back button event and does nothing (or shows a warning). The lower-priority router handler never fires.
Step 6 : Use Capacitor App Plugin for Back Button
Capacitor has its own App plugin that provides a backButton event. This is the native Capacitor way — useful when we need back button handling outside of the Angular/Ionic framework context, or for more control.
Install the plugin if not already present :
npm install @capacitor/app
npx cap sync
Use it in our component or service :
import { Component, OnInit } from '@angular/core';
import { App } from '@capacitor/app';
import { AlertController } from '@ionic/angular';
@Component({
selector: 'app-root',
template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`
})
export class AppComponent implements OnInit {
constructor(private alertController: AlertController) {}
ngOnInit() {
App.addListener('backButton', async ({ canGoBack }) => {
if (canGoBack) {
window.history.back();
} else {
await this.showExitAlert();
}
});
}
private async showExitAlert() {
const alert = await this.alertController.create({
header: 'Exit App',
message: 'Do you want to exit the app?',
buttons: [
{ text: 'Cancel', role: 'cancel' },
{
text: 'Exit',
handler: () => App.exitApp() // Clean Capacitor way to exit
}
]
});
await alert.present();
}
}
canGoBack is provided by Capacitor — it's true if the WebView has history to go back to. App.exitApp() cleanly closes the app the Capacitor way.
The difference between this and Platform.backButton — Capacitor's App.addListener is lower level and doesn't have the priority system. For simple apps with no modals or menus this is cleaner. For apps with modals and overlays, Platform.backButton with priorities is more flexible.
Step 7 : Handle Back Button in Standalone Angular App
If we're using Angular standalone components without AppModule, set up the back button handler in the root AppComponent using inject() :
import { Component, OnInit } from '@angular/core';
import { Platform, AlertController, IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
import { Location } from '@angular/common';
@Component({
selector: 'app-root',
standalone: true,
imports: [IonApp, IonRouterOutlet],
template: `<ion-app><ion-router-outlet></ion-router-outlet></ion-app>`
})
export class AppComponent implements OnInit {
constructor(
private platform: Platform,
private alertController: AlertController,
private location: Location
) {}
ngOnInit() {
this.platform.backButton.subscribeWithPriority(10, async () => {
if (window.history.length > 1) {
this.location.back();
} else {
const alert = await this.alertController.create({
header: 'Exit',
message: 'Exit the app?',
buttons: [
{ text: 'No', role: 'cancel' },
{ text: 'Yes', handler: () => App.exitApp() }
]
});
await alert.present();
}
});
}
}
Same logic — just using standalone component imports instead of NgModule.
Priority Reference — Quick Guide
Here's a summary of what priority levels to use for different scenarios :
| Scenario | Priority |
|---|---|
| Default Ionic router | 0 |
| App-level back handler | 10 |
| Page-level custom handler | 15 |
| Modal / Popover close | 20 |
| Alert / Confirm dialog | 25 |
| Block navigation (payment etc) | 30 |
Higher priority always wins. When a modal is open at priority 20, the app-level handler at 10 doesn't fire. When the modal is dismissed and its listener is unsubscribed, the app-level handler takes over again automatically.
Common Issues
Back button exits app without confirmation
Our global handler isn't registered or is registered at priority 0 which doesn't override the default router. Use priority 10 or higher.
Modal dismisses AND navigates back
The modal's back button handler is at the same or lower priority as the app-level handler. Set the modal handler to priority 20 and the app handler to priority 10.
Back button does nothing in browser during development
Platform.backButton only fires for the hardware/software back button on Android. In the browser, the back button in the toolbar navigates the browser itself, not our app's handler. Test back button behaviour on a real device or Android emulator.
Handler fires multiple times
We're subscribing to the back button in a component that gets created and destroyed multiple times without unsubscribing. Always unsubscribe() in ngOnDestroy(). Or better — handle global back button in AppComponent which lives for the app's lifetime and never gets destroyed.
Summary
We learned how to handle the Android back button in Ionic Capacitor apps. We covered :
- How Ionic's back button event system works with priority levels
- Setting up a global back button handler in AppComponent
- Showing an exit confirmation alert when pressing back on the root page
- Closing modals on back button press with higher priority listener
- Closing side menu before navigating back
- Blocking back navigation on sensitive screens like payment processing
- Using Capacitor's App plugin
backButtonlistener andApp.exitApp()for clean exit - Priority reference table for different overlay scenarios
- Common issues like multiple firings, browser testing limitations, and modal + navigation conflict
The key rule — register at a higher priority to take control, unsubscribe in ngOnDestroy to give it back. Once we understand the priority system, back button handling clicks into place.
I hope you like this article...
Happy coding! 🚀
0 Comments