Search docs/
scoped

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 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;
}
CopyCopied

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;
}
CopyCopied

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

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
    });
    return await popover.present();
  }
}
CopyCopied

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.

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);
  return popover.present();
}
CopyCopied
import React, { useState } from 'react';
import { IonPopover, IonButton } from '@ionic/react';

export const PopoverExample: React.FC = () => {
  const [showPopover, setShowPopover] = useState(false);

  return (
    <>
      <IonPopover
        isOpen={showPopover}
        cssClass='my-custom-class'
        onDidDismiss={e => setShowPopover(false)}
      >
        <p>This is popover content</p>
      </IonPopover>
      <IonButton onClick={() => setShowPopover(true)}>Show Popover</IonButton>
    </>
  );
};
CopyCopied
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
    });
    return await popover.present();
  }

  render() {
    return [
      <ion-content>
        <ion-button onClick={(ev) => this.presentPopover(ev)}>Present Popover</ion-button>
      </ion-content>
    ];
  }
}
CopyCopied
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>
    ];
  }
}
CopyCopied
<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>
CopyCopied
<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
        })
      return popover.present();
    },
  },
}
</script>
CopyCopied

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"
    @onDidDismiss="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, event?: Event) => {
      event.value = event; 
      isOpenRef.value = state;
    }
    return { isOpenRef, setOpen, event }
  }
});
</script>
CopyCopied

Properties

animated

Description

If true, the popover will animate.

Attributeanimated
Typeboolean
Defaulttrue

backdropDismiss

Description

If true, the popover will be dismissed when the backdrop is clicked.

Attributebackdrop-dismiss
Typeboolean
Defaulttrue

component

Description

The component to display inside of the popover.

Attributecomponent
TypeFunction | HTMLElement | null | string

componentProps

Description

The data to pass to the popover component.

Typeundefined | { [key: string]: any; }

cssClass

Description

Additional classes to apply for custom CSS. If multiple classes are provided they should be separated by spaces.

Attributecss-class
Typestring | string[] | undefined

enterAnimation

Description

Animation to use when the popover is presented.

Type((baseEl: any, opts?: any) => Animation) | undefined

event

Description

The event to pass to the popover animation.

Attributeevent
Typeany

keyboardClose

Description

If true, the keyboard will be automatically dismissed when the overlay is presented.

Attributekeyboard-close
Typeboolean
Defaulttrue

leaveAnimation

Description

Animation to use when the popover is dismissed.

Type((baseEl: any, opts?: any) => Animation) | undefined

mode

Description

The mode determines which platform styles to use.

Attributemode
Type"ios" | "md"

showBackdrop

Description

If true, a backdrop will be displayed behind the popover.

Attributeshow-backdrop
Typeboolean
Defaulttrue

translucent

Description

If true, the popover will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter.

Attributetranslucent
Typeboolean
Defaultfalse

Events

NameDescription
ionPopoverDidDismissEmitted after the popover has dismissed.
ionPopoverDidPresentEmitted after the popover has presented.
ionPopoverWillDismissEmitted before the popover has dismissed.
ionPopoverWillPresentEmitted before the popover has presented.

Methods

dismiss

Description

Dismiss the popover overlay after it has been presented.

Signaturedismiss(data?: any, role?: string | undefined) => Promise<boolean>

onDidDismiss

Description

Returns a promise that resolves when the popover did dismiss.

SignatureonDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description

Returns a promise that resolves when the popover will dismiss.

SignatureonWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

Description

Present the popover overlay after it has been created.

Signaturepresent() => Promise<void>

CSS Custom Properties

NameDescription
--backdrop-opacityOpacity of the backdrop
--backgroundBackground of the popover
--box-shadowBox shadow of the popover
--heightHeight of the popover
--max-heightMaximum height of the popover
--max-widthMaximum width of the popover
--min-heightMinimum height of the popover
--min-widthMinimum width of the popover
--widthWidth of the popover
View Source