Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Components and Theming

Ionic Modals, Alerts, Toasts and Popovers

Learn every Ionic overlay: alert, action sheet, toast, loading, popover and modal. When to use each, how to open them, return data and dismiss them.

An overlay is UI that appears above the current page: a confirmation dialog, a message that fades away, a sheet of choices. Ionic provides six overlay types with a shared lifecycle: create, present, dismiss. Choosing the right one is half the job, and the rest is learning the shared patterns for opening, closing and returning data.

Which overlay for which job

Overlay Use it for Blocks the page?
ion-alert Short message, confirm or cancel, or a small prompt Yes
ion-action-sheet Pick one action from a short list (share, delete, cancel) Yes
ion-toast Brief non-blocking feedback ("Saved") No
ion-loading Spinner while waiting for something Yes
ion-popover Small contextual menu anchored to an element Light dismiss
ion-modal A full task: a form, a detail page, a sheet Yes

Pick the lightest overlay

Toast Just tell the user
Alert Ask a yes or no
1 / 2

The create, present, dismiss lifecycle

Controllers create overlays from code. In plain TypeScript with @ionic/core controllers (the framework packages wrap them as AlertController, useIonAlert and so on):

TypeScript
import { alertController, toastController } from '@ionic/core';

async function confirmDelete(): Promise<boolean> {
  const alert = await alertController.create({
    header: 'Delete note?',
    message: 'This cannot be undone.',
    buttons: [
      { text: 'Cancel', role: 'cancel' },
      { text: 'Delete', role: 'destructive' },
    ],
  });
  await alert.present();
  const { role } = await alert.onDidDismiss();
  return role === 'destructive';
}

async function showSaved() {
  const toast = await toastController.create({
    message: 'Note saved',
    duration: 1800,
    position: 'bottom',
    color: 'success',
  });
  await toast.present();
}

Key ideas: create() builds the overlay, present() shows it, and onDidDismiss() resolves with { data, role } when it closes. The role of a button (cancel, destructive, confirm) is passed on and also tells Ionic how to style it.

Alerts with inputs

An alert can also collect a single short value:

TypeScript
const alert = await alertController.create({
  header: 'Rename',
  inputs: [{ name: 'title', type: 'text', placeholder: 'New title' }],
  buttons: [
    { text: 'Cancel', role: 'cancel' },
    { text: 'OK', role: 'confirm' },
  ],
});
await alert.present();
const { data, role } = await alert.onDidDismiss();
if (role === 'confirm') console.log(data.values.title);

For anything more than one or two inputs, use a modal with a real form (forms and validation).

Modals

A modal presents a whole component. The declarative form is easiest:

HTML
<ion-button id="open-modal">Open</ion-button>
<ion-modal trigger="open-modal" (willDismiss)="onWillDismiss($event)">
  <ng-template>
    <ion-header>
      <ion-toolbar>
        <ion-buttons slot="start">
          <ion-button (click)="modal.dismiss(null, 'cancel')">Cancel</ion-button>
        </ion-buttons>
        <ion-title>New note</ion-title>
        <ion-buttons slot="end">
          <ion-button strong (click)="modal.dismiss(title, 'confirm')">Save</ion-button>
        </ion-buttons>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">...</ion-content>
  </ng-template>
</ion-modal>

Modals have a few notable modes:

  • Card modal on iOS (presentingElement) stacks over the page with a swipe-down handle.
  • Sheet modal (breakpoints=[0, 0.25, 0.5, 1], initialBreakpoint) slides up to resting heights, like a map app's bottom panel.
  • Inline vs controller: inline (declarative) is simplest; controller-created modals suit one-off, dynamic ones.

Data comes back through dismiss(data, role), which resolves onWillDismiss or onDidDismiss.

Popovers

A popover points at the element that opened it:

HTML
<ion-button id="menu-btn">More</ion-button>
<ion-popover trigger="menu-btn" triggerAction="click">
  <ng-template>
    <ion-content><ion-list>
      <ion-item button>Rename</ion-item>
      <ion-item button>Duplicate</ion-item>
    </ion-list></ion-content>
  </ng-template>
</ion-popover>

On phones a popover covers a small part of the screen; on tablets and desktops it sits near its trigger.

Stand-in: the overlay lifecycle as a promise

Presenting an overlay is asynchronous and the result is a promise. This stand-in models create, present and onDidDismiss with a tiny class, so you can practise the control flow, including what happens for cancel and confirm.

JS Stand-in: create, present, dismiss

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

No output.

A toast queue

Showing several toasts at once looks messy. A common pattern is a queue that shows one at a time. This is a runnable stand-in of the queue logic:

JS Stand-in: show one toast at a time

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

No output.

Good practices

  • Keep alert text short; put the verb on the button ("Delete", not "OK").
  • Mark destructive actions with role: 'destructive'.
  • Toasts must not hold critical information; they disappear and can be missed. Give them a duration and an aria-live friendly message.
  • Always dismiss loading overlays in a finally block, or an error will leave a spinner stuck forever.
  • Modals restore focus to the opener on close; keep that behaviour by not removing the trigger while open.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which overlay is best for 'Saved' feedback?

    A toast is non-blocking and disappears on its own, ideal for brief feedback.
  2. 2. What does onDidDismiss resolve with?

    It resolves with { data, role } so you know how and with what the overlay was closed.
  3. 3. Where should you hide a loading overlay?

    An error that skips the dismiss call leaves the spinner on screen.
  4. 4. Which modal style slides up to resting heights?

    A sheet modal uses breakpoints and initialBreakpoint for resting heights.

Summary

  • Six overlays: alert, action sheet, toast, loading, popover, modal; use the lightest that fits.
  • Overlays are created, presented and dismissed, with results in { data, role }.
  • Modals carry full tasks and can be card or sheet styled.
  • Always dismiss loaders in finally; give destructive buttons the right role.

Next: Theming with CSS Variables