Skip to main content

ion-modal

View Source

A Modal is a dialog that appears on top of the app's content, and must be dismissed by the app before interaction can resume. It is useful as a select component when there are a lot of options to choose from, or when filtering items in a list, as well as many other use cases.

Presenting#

There are two ways to use ion-modal: inline or via the modalController. Each method comes with different considerations, so be sure to use the approach that best fits your use case.

Inline Modals#

ion-modal can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the modal. See Usage for an example of how to write a modal inline.

When using ion-modal with Angular, React, or Vue, the component you pass in will be destroyed when the modal is dismissed. As this functionality is provided by the JavaScript framework, using ion-modal without a JavaScript framework will not destroy the component you passed in. If this is a needed functionality, we recommend using the modalController instead.

Angular#

Since the component you passed in needs to be created when the modal is presented and destroyed when the modal is dismissed, we are unable to project the content using <ng-content> internally. Instead, we use <ng-container> which expects an <ng-template> to be passed in. As a result, when passing in your component you will need to wrap it in an <ng-template>:

<ion-modal [isOpen]="isModalOpen">
<ng-template>
<app-modal-content></app-modal-content>
</ng-template>
</ion-modal>

When to use#

Using a modal inline is useful when you do not want to explicitly wire up click events to open the modal. For example, you can use the is-open property to easily present or dismiss a modal based on some state in your application.

If you need fine grained control over when the modal is presented and dismissed, we recommend you use the modalController.

Controller Modals#

ion-modal can also be presented programmatically by using the modalController imported from Ionic Framework. This allows you to have complete control over when a modal is presented above and beyond the customization that inline modals give you. See Usage for an example of how to use the modalController.

When to use#

We typically recommend that you write your modals inline as it streamlines the amount of code in your application. You should only use the modalController for complex use cases where writing a modal inline is impractical.

Interfaces#

Below you will find all of the options available to you when using the modalController. These options should be supplied when calling modalController.create().

interface ModalOptions {
component: any;
componentProps?: { [key: string]: any };
presentingElement?: HTMLElement;
showBackdrop?: boolean;
backdropDismiss?: boolean;
cssClass?: string | string[];
animated?: boolean;
swipeToClose?: boolean;
mode?: 'ios' | 'md';
keyboardClose?: boolean;
id?: string;
enterAnimation?: AnimationBuilder;
leaveAnimation?: AnimationBuilder;
}

Dismissing#

The modal can be dismissed after creation by calling the dismiss() method on the modal controller. The onDidDismiss function can be called to perform an action after the modal is dismissed.

Customization#

Modal uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector.

We recommend passing a custom class to cssClass in the create method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. View the Usage section for an example of how to pass a class using cssClass.

/* DOES NOT WORK - not specific enough */
.modal-wrapper {
background: #222;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .modal-wrapper {
background: #222;
}

Any of the defined CSS Custom Properties can be used to style the Modal without needing to target individual elements:

.my-custom-class {
--background: #222;
}

If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read Style Placement in the Angular section below for more information.

ion-modal works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of 0. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the --box-shadow and --backdrop-opacity CSS variables:

ion-modal.stack-modal {
--box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
--backdrop-opacity: var(--ion-backdrop-opacity, 0.32);
}

Usage#

import { Component } from '@angular/core';
import { ModalController } from '@ionic/angular';
import { ModalPage } from '../modal/modal.page';
@Component({
selector: 'modal-example',
templateUrl: 'modal-example.html',
styleUrls: ['./modal-example.css']
})
export class ModalExample {
constructor(public modalController: ModalController) {
}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class'
});
return await modal.present();
}
}
import { Component, Input } from '@angular/core';
@Component({
selector: 'modal-page',
})
export class ModalPage {
constructor() {}
}

If you need a wrapper element inside of your modal component, we recommend using a <div class="ion-page"> so that the component dimensions are still computed properly.

Passing Data#

During creation of a modal, data can be passed in through the componentProps. The previous example can be written to include data:

async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
componentProps: {
'firstName': 'Douglas',
'lastName': 'Adams',
'middleInitial': 'N'
}
});
return await modal.present();
}

To get the data passed into the componentProps, set it as an @Input:

export class ModalPage {
// Data passed in by componentProps
@Input() firstName: string;
@Input() lastName: string;
@Input() middleInitial: string;
}

Dismissing a Modal#

A modal can be dismissed by calling the dismiss method on the modal controller and optionally passing any data from the modal.

export class ModalPage {
...
dismiss() {
// using the injected ModalController this page
// can "dismiss" itself and optionally pass back data
this.modalController.dismiss({
'dismissed': true
});
}
}

After being dismissed, the data can be read in through the onWillDismiss or onDidDismiss attached to the modal after creation:

const { data } = await modal.onWillDismiss();
console.log(data);

Lazy Loading#

When lazy loading a modal, it's important to note that the modal will not be loaded when it is opened, but rather when the module that imports the modal's module is loaded.

For example, say there exists a CalendarComponent and an EventModal. The modal is presented by clicking a button in the CalendarComponent. In Angular, the EventModalModule would need to be included in the CalendarComponentModule since the modal is created in the CalendarComponent:

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { IonicModule } from '@ionic/angular';
import { CalendarComponent } from './calendar.component';
import { EventModalModule } from '../modals/event/event.module';
@NgModule({
declarations: [
CalendarComponent
],
imports: [
IonicModule,
CommonModule,
EventModalModule
],
exports: [
CalendarComponent
]
})
export class CalendarComponentModule {}

Swipeable Modals#

Modals in iOS mode have the ability to be presented in a card-style and swiped to close. The card-style presentation and swipe to close gesture are not mutually exclusive, meaning you can pick and choose which features you want to use. For example, you can have a card-style modal that cannot be swiped or a full sized modal that can be swiped.

Card style modals when running on iPhone-sized devices do not have backdrops. As a result, the --backdrop-opacity variable will not have any effect.

If you are creating an application that uses ion-tabs, it is recommended that you get the parent ion-router-outlet using this.routerOutlet.parentOutlet.nativeEl, otherwise the tabbar will not scale down when the modal opens.

import { IonRouterOutlet } from '@ionic/angular';
constructor(private routerOutlet: IonRouterOutlet) {}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: this.routerOutlet.nativeEl
});
return await modal.present();
}

In most scenarios, using the ion-router-outlet element as the presentingElement is fine. In cases where you are presenting a card-style modal from within another modal, you should pass in the top-most ion-modal element as the presentingElement.

import { ModalController } from '@ionic/angular';
constructor(private modalController: ModalController) {}
async presentModal() {
const modal = await this.modalController.create({
component: ModalPage,
cssClass: 'my-custom-class',
swipeToClose: true,
presentingElement: await this.modalController.getTop() // Get the top-most ion-modal
});
return await modal.present();
}

Style Placement#

In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Modal can be presented from within a page, the ion-modal element is appended outside of the current page. This means that any custom styles need to go in a global stylesheet file. In an Ionic Angular starter this can be the src/global.scss file or you can register a new global style file by adding to the styles build option in angular.json.

Properties#

animated#

DescriptionIf true, the modal will animate.
Attributeanimated
Typeboolean
Defaulttrue

backdropDismiss#

DescriptionIf true, the modal will be dismissed when the backdrop is clicked.
Attributebackdrop-dismiss
Typeboolean
Defaulttrue

enterAnimation#

DescriptionAnimation to use when the modal is presented.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) \| undefined
Defaultundefined

isOpen#

DescriptionIf true, the modal will open. If false, the modal will close.
Use this if you need finer grained control over presentation, otherwise
just use the modalController or the trigger property.
Note: isOpen will not automatically be set back to false when
the modal dismisses. You will need to do that in your code.
Attributeis-open
Typeboolean
Defaultfalse

keyboardClose#

DescriptionIf true, the keyboard will be automatically dismissed when the overlay is presented.
Attributekeyboard-close
Typeboolean
Defaulttrue

leaveAnimation#

DescriptionAnimation to use when the modal is dismissed.
Attributeundefined
Type((baseEl: any, opts?: any) => Animation) \| undefined
Defaultundefined

mode#

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" \| "md"
Defaultundefined

presentingElement#

DescriptionThe element that presented the modal. This is used for card presentation effects
and for stacking multiple modals on top of each other. Only applies in iOS mode.
Attributeundefined
TypeHTMLElement \| undefined
Defaultundefined

showBackdrop#

DescriptionIf true, a backdrop will be displayed behind the modal.
Attributeshow-backdrop
Typeboolean
Defaulttrue

swipeToClose#

DescriptionIf true, the modal can be swiped to dismiss. Only applies in iOS mode.
Attributeswipe-to-close
Typeboolean
Defaultfalse

trigger#

DescriptionAn ID corresponding to the trigger element that
causes the modal to open when clicked.
Attributetrigger
Typestring \| undefined
Defaultundefined

Events#

NameDescription
didDismissEmitted after the modal has dismissed.
Shorthand for ionModalDidDismiss.
didPresentEmitted after the modal has presented.
Shorthand for ionModalWillDismiss.
ionModalDidDismissEmitted after the modal has dismissed.
ionModalDidPresentEmitted after the modal has presented.
ionModalWillDismissEmitted before the modal has dismissed.
ionModalWillPresentEmitted before the modal has presented.
willDismissEmitted before the modal has dismissed.
Shorthand for ionModalWillDismiss.
willPresentEmitted before the modal has presented.
Shorthand for ionModalWillPresent.

Methods#

dismiss#

DescriptionDismiss the modal overlay after it has been presented.
Signaturedismiss(data?: any, role?: string \| undefined) => Promise<boolean>

onDidDismiss#

DescriptionReturns a promise that resolves when the modal did dismiss.
SignatureonDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss#

DescriptionReturns a promise that resolves when the modal will dismiss.
SignatureonWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present#

DescriptionPresent the modal overlay after it has been created.
Signaturepresent() => Promise<void>

CSS Shadow Parts#

NameDescription
backdropThe ion-backdrop element.
contentThe wrapper element for the default slot.

CSS Custom Properties#

NameDescription
--backdrop-opacityOpacity of the backdrop
--backgroundBackground of the modal content
--border-colorBorder color of the modal content
--border-radiusBorder radius of the modal content
--border-styleBorder style of the modal content
--border-widthBorder width of the modal content
--heightHeight of the modal
--max-heightMaximum height of the modal
--max-widthMaximum width of the modal
--min-heightMinimum height of the modal
--min-widthMinimum width of the modal
--widthWidth of the modal

Slots#

NameDescription
= Content is placed inside of the .modal-content element.