ion-popover
A Popover is a dialog that appears on top of the current page. It can be used for anything, but generally it is used for overflow actions that don't fit in the navigation bar.
Presenting
To present a popover, call the present
method on a popover instance. In order to position the popover relative to the element clicked, a click event needs to be passed into the options of the present
method. If the event is not passed, the popover will be positioned in the center of the viewport.
Customization
Popover 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 */
.popover-content {
background: #222;
}
/* Works - pass "my-custom-class" in cssClass to increase specificity */
.my-custom-class .popover-content {
background: #222;
}
Any of the defined CSS Custom Properties can be used to style the Popover 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.
Usage
- Angular
- Javascript
- React
- Stencil
- Vue
import { Component } from '@angular/core';
import { PopoverController } from '@ionic/angular';
import { PopoverComponent } from '../../component/popover/popover.component';
@Component({
selector: 'popover-example',
templateUrl: 'popover-example.html',
styleUrls: ['./popover-example.css'],
})
export class PopoverExample {
constructor(public popoverController: PopoverController) {}
async presentPopover(ev: any) {
const popover = await this.popoverController.create({
component: PopoverComponent,
cssClass: 'my-custom-class',
event: ev,
translucent: true,
});
await popover.present();
const { role } = await popover.onDidDismiss();
console.log('onDidDismiss resolved with role', role);
}
}
Style Placement
In Angular, the CSS of a specific page is scoped only to elements of that page. Even though the Popover can be presented from within a page, the ion-popover
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
.
class PopoverExamplePage extends HTMLElement {
constructor() {
super();
}
connectedCallback() {
this.innerHTML = `
<ion-content>
<ion-list>
<ion-list-header><ion-label>Ionic</ion-label></ion-list-header>
<ion-item button><ion-label>Item 0</ion-label></ion-item>
<ion-item button><ion-label>Item 1</ion-label></ion-item>
<ion-item button><ion-label>Item 2</ion-label></ion-item>
<ion-item button><ion-label>Item 3</ion-label></ion-item>
</ion-list>
</ion-content>
`;
}
}
customElements.define('popover-example-page', PopoverExamplePage);
function presentPopover(ev) {
const popover = Object.assign(document.createElement('ion-popover'), {
component: 'popover-example-page',
cssClass: 'my-custom-class',
event: ev,
translucent: true,
});
document.body.appendChild(popover);
await popover.present();
const { role } = await popover.onDidDismiss();
console.log('onDidDismiss resolved with role', role);
}
/* Using with useIonPopover Hook */
import React from 'react';
import { IonButton, IonContent, IonItem, IonList, IonListHeader, IonPage, useIonPopover } from '@ionic/react';
const PopoverList: React.FC<{
onHide: () => void;
}> = ({ onHide }) => (
<IonList>
<IonListHeader>Ionic</IonListHeader>
<IonItem button>Learn Ionic</IonItem>
<IonItem button>Documentation</IonItem>
<IonItem button>Showcase</IonItem>
<IonItem button>GitHub Repo</IonItem>
<IonItem lines="none" detail={false} button onClick={onHide}>
Close
</IonItem>
</IonList>
);
const PopoverExample: React.FC = () => {
const [present, dismiss] = useIonPopover(PopoverList, {
onHide: () => dismiss(),
});
return (
<IonPage>
<IonContent>
<IonButton
expand="block"
onClick={(e) =>
present({
event: e.nativeEvent,
})
}
>
Show Popover
</IonButton>
</IonContent>
</IonPage>
);
};
/* Using with IonPopover Component */
import React, { useState } from 'react';
import { IonPopover, IonButton } from '@ionic/react';
export const PopoverExample: React.FC = () => {
const [popoverState, setShowPopover] = useState({
showPopover: false,
event: undefined,
});
return (
<>
<IonPopover
cssClass="my-custom-class"
event={popoverState.event}
isOpen={popoverState.showPopover}
onDidDismiss={() => setShowPopover({ showPopover: false, event: undefined })}
>
<p>This is popover content</p>
</IonPopover>
<IonButton
onClick={(e: any) => {
e.persist();
setShowPopover({ showPopover: true, event: e });
}}
>
Show Popover
</IonButton>
</>
);
};
import { Component, h } from '@stencil/core';
import { popoverController } from '@ionic/core';
@Component({
tag: 'popover-example',
styleUrl: 'popover-example.css',
})
export class PopoverExample {
async presentPopover(ev: any) {
const popover = await popoverController.create({
component: 'page-popover',
cssClass: 'my-custom-class',
event: ev,
translucent: true,
});
await popover.present();
const { role } = await popover.onDidDismiss();
console.log('onDidDismiss resolved with role', role);
}
render() {
return [
<ion-content>
<ion-button onClick={(ev) => this.presentPopover(ev)}>Present Popover</ion-button>
</ion-content>,
];
}
}
import { Component, h } from '@stencil/core';
@Component({
tag: 'page-popover',
styleUrl: 'page-popover.css',
})
export class PagePopover {
render() {
return [
<ion-list>
<ion-item>
<ion-label>Documentation</ion-label>
</ion-item>
<ion-item>
<ion-label>Feedback</ion-label>
</ion-item>
<ion-item>
<ion-label>Settings</ion-label>
</ion-item>
</ion-list>,
];
}
}
<template>
<ion-content class="ion-padding"> Popover Content </ion-content>
</template>
<script>
import { IonContent } from '@ionic/vue';
import { defineComponent } from 'vue';
export default defineComponent({
name: 'Popover',
components: { IonContent },
});
</script>
<template>
<ion-page>
<ion-content class="ion-padding">
<ion-button @click="openPopover">Open Popover</ion-button>
</ion-content>
</ion-page>
</template>
<script>
import { IonButton, IonContent, IonPage, popoverController } from '@ionic/vue';
import Popver from './popover.vue';
export default {
components: { IonButton, IonContent, IonPage },
methods: {
async openPopover(ev: Event) {
const popover = await popoverController.create({
component: Popover,
cssClass: 'my-custom-class',
event: ev,
translucent: true,
});
await popover.present();
const { role } = await popover.onDidDismiss();
console.log('onDidDismiss resolved with role', role);
},
},
};
</script>
Developers can also use this component directly in their template:
<template>
<ion-button @click="setOpen(true, $event)">Show Popover</ion-button>
<ion-popover
:is-open="isOpenRef"
css-class="my-custom-class"
:event="event"
:translucent="true"
@didDismiss="setOpen(false)"
>
<Popover></Popover>
</ion-popover>
</template>
<script>
import { IonButton, IonPopover } from '@ionic/vue';
import { defineComponent, ref } from 'vue';
import Popver from './popover.vue';
export default defineComponent({
components: { IonButton, IonPopover, Popover },
setup() {
const isOpenRef = ref(false);
const event = ref();
const setOpen = (state: boolean, ev?: Event) => {
event.value = ev;
isOpenRef.value = state;
};
return { isOpenRef, setOpen, event };
},
});
</script>
Properties
animated
Description | If true , the popover will animate. |
Attribute | animated |
Type | boolean |
Default | true |
backdropDismiss
Description | If true , the popover will be dismissed when the backdrop is clicked. |
Attribute | backdrop-dismiss |
Type | boolean |
Default | true |
component
Description | The component to display inside of the popover. |
Attribute | component |
Type | Function | HTMLElement | null | string |
Default | undefined |
componentProps
Description | The data to pass to the popover component. |
Attribute | undefined |
Type | undefined | { [key: string]: any; } |
Default | undefined |
cssClass
Description | Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces. |
Attribute | css-class |
Type | string | string[] | undefined |
Default | undefined |
enterAnimation
Description | Animation to use when the popover is presented. |
Attribute | undefined |
Type | ((baseEl: any, opts?: any) => Animation) | undefined |
Default | undefined |
event
Description | The event to pass to the popover animation. |
Attribute | event |
Type | any |
Default | undefined |
htmlAttributes
Description | Additional attributes to pass to the popover. |
Attribute | undefined |
Type | PopoverAttributes | undefined |
Default | undefined |
keyboardClose
Description | If true , the keyboard will be automatically dismissed when the overlay is presented. |
Attribute | keyboard-close |
Type | boolean |
Default | true |
leaveAnimation
Description | Animation to use when the popover is dismissed. |
Attribute | undefined |
Type | ((baseEl: any, opts?: any) => Animation) | undefined |
Default | undefined |
mode
Description | The mode determines which platform styles to use. |
Attribute | mode |
Type | "ios" | "md" |
Default | undefined |
showBackdrop
Description | If true , a backdrop will be displayed behind the popover. |
Attribute | show-backdrop |
Type | boolean |
Default | true |
translucent
Description | If true , the popover will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter . |
Attribute | translucent |
Type | boolean |
Default | false |
Events
Name | Description |
---|---|
ionPopoverDidDismiss | Emitted after the popover has dismissed. |
ionPopoverDidPresent | Emitted after the popover has presented. |
ionPopoverWillDismiss | Emitted before the popover has dismissed. |
ionPopoverWillPresent | Emitted before the popover has presented. |
Methods
dismiss
Description | Dismiss the popover overlay after it has been presented. |
Signature | dismiss(data?: any, role?: string | undefined) => Promise<boolean> |
onDidDismiss
Description | Returns a promise that resolves when the popover did dismiss. |
Signature | onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
onWillDismiss
Description | Returns a promise that resolves when the popover will dismiss. |
Signature | onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
present
Description | Present the popover overlay after it has been created. |
Signature | present() => Promise<void> |
CSS Shadow Parts
No CSS shadow parts available for this component.
CSS Custom Properties
Name | Description |
---|---|
--backdrop-opacity | Opacity of the backdrop |
--background | Background of the popover |
--box-shadow | Box shadow of the popover |
--height | Height of the popover |
--max-height | Maximum height of the popover |
--max-width | Maximum width of the popover |
--min-height | Minimum height of the popover |
--min-width | Minimum width of the popover |
--width | Width of the popover |
Slots
No slots available for this component.