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

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.

Javascript

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

React

/* 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>
    </>
  );
};

Stencil

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>,
    ];
  }
}

Vue

<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	trueの場合、ポップオーバーはアニメーションを行います。
Attribute	animated
Type	boolean
Default	true

backdropDismiss

Description	trueの場合、バックドロップがクリックされたときにポップオーバーが解除される。
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	ポップオーバーが表示されたときに使用するアニメーションです。
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

event

Description	ポップオーバー・アニメーションに渡すイベントです。
Attribute	event
Type	any
Default	undefined

htmlAttributes

Description	ポップオーバーに渡す追加属性。
Attribute	undefined
Type	PopoverAttributes ｜ undefined
Default	undefined

keyboardClose

Description	trueの場合、オーバーレイが表示されたときにキーボードが自動的に解除されます。
Attribute	keyboard-close
Type	boolean
Default	true

leaveAnimation

Description	ポップオーバーが解除されたときに使用するアニメーションです。
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
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	ポップオーバーが解除された後に発行されます。
ionPopoverDidPresent	ポップオーバーが表示された後に発行されます。
ionPopoverWillDismiss	ポップオーバーが解除される前に発行されます。
ionPopoverWillPresent	ポップオーバーが表示される前に発行されます。

Methods

dismiss

Description	ポップオーバーオーバーレイが提示された後、それを解除します。
Signature	dismiss(data?: any, role?: string ｜ undefined) => Promise<boolean>

onDidDismiss

Description	ポップオーバーが解除されたタイミングを解決するPromiseを返します。
Signature	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description	ポップオーバーが解除されるタイミングを解決するPromiseを返します。
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	背景の不透明度
--background	ポップオーバーの背景
--box-shadow	ポップオーバーのボックスシャドウ
--height	ポップオーバーの高さ
--max-height	ポップオーバーの最大の高さ
--max-width	ポップオーバーの最大幅
--min-height	ポップオーバーの高さの最小値
--min-width	ポップオーバーの最小幅
--width	ポップオーバーの幅

Slots

No slots available for this component.