Version: v6

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.

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

Inline Popovers

ion-popover 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 popover.

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

When to use

Using a popover inline is useful when you do not want to explicitly wire up click events to open the popover. For example, you can use the trigger property to designate a button that should present the popover when clicked. You can also use the trigger-action property to customize whether the popover should be presented when the trigger is left clicked, right clicked, or hovered over.

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

Angular

Since the component you passed in needs to be created when the popover is presented and destroyed when the popover 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-popover [isOpen]="isPopoverOpen">
  <ng-template>
    <app-popover-content></app-popover-content>
  </ng-template>
</ion-popover>

Triggers

A trigger for an inline ion-popover is the element that will open a popover when interacted with. The interaction behavior can be customized by setting the trigger-action property. Note that trigger-action="context-menu" will prevent your system's default context menu from opening.

note

Triggers are not applicable when using the popoverController because the ion-popover is not created ahead of time.

isOpen Property

Inline popovers can also be opened by setting the isOpen property to true. This method can be used if you need finer grained control over the popover than with a trigger.

isOpen uses a one-way data binding, meaning it will not automatically be set to false when the popover is dismissed. Developers should listen for the ionPopoverDidDismiss or didDismiss event and set isOpen to false. The reason for this is it prevents the internals of ion-popover from being tightly coupled with the state of the application. With a one way data binding, the popover only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the popover needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.

Controller Popovers

ion-popover can also be presented programmatically by using the popoverController imported from Ionic Framework. This allows you to have complete control over when a popover is presented above and beyond the customization that inline popovers give you.

When to use

We typically recommend that you write your popovers inline as it streamlines the amount of code in your application. You should only use the popoverController for complex use cases where writing a popover inline is impractical. When using a controller, your popover is not created ahead of time, so properties such as trigger and trigger-action are not applicable here. In addition, nested popovers are not compatible with the controller approach because the popover is automatically added to the root of your application when the create method is called.

React

Instead of a controller, React has a hook called useIonPopover which behaves in a similar fashion. Note that useIonPopover requires being a descendant of <IonApp>. If you need to use a popover outside of an <IonApp>, consider using an inline popover instead.

Usage

Styling

Popovers are presented at the root of your application so they overlay your entire app. This behavior applies to both inline popovers and popovers presented from a controller. As a result, custom popover styles can not be scoped to a particular component as they will not apply to the popover. Instead, styles must be applied globally. For most developers, placing the custom styles in global.css is sufficient.

note

If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.

Positioning

Reference

When presenting a popover, Ionic Framework needs a reference point to present the popover relative to. With reference="event", the popover will be presented relative to the x-y coordinates of the pointer event that was dispatched on your trigger element. With reference="trigger", the popover will be presented relative to the bounding box of your trigger element.

Side

Regardless of what you choose for your reference point, you can position a popover to the top, right, left, or bottom of your reference point by using the side property. You can also use the start or end values if you would like the side to switch based on LTR or RTL modes.

Alignment

The alignment property allows you to line up an edge of your popover with a corresponding edge on your trigger element. The exact edge that is used depends on the value of the side property.

Side and Alignment Demo

Offsets

If you need finer grained control over the positioning of your popover you can use the --offset-x and --offset-y CSS Variables. For example, --offset-x: 10px will move your popover content to the right by 10px.

Sizing

When making dropdown menus, you may want to have the width of the popover match the width of the trigger element. Doing this without knowing the trigger width ahead of time is tricky. You can set the size property to 'cover' and Ionic Framework will ensure that the width of the popover matches the width of your trigger element.

If you are using the popoverController, you must provide an event via the event option and Ionic Framework will use event.target as the reference element. See the controller demo for an example of this pattern.

Nested Popovers

When using ion-popover inline, you can nested popovers to create nested dropdown menus. When doing this, only the backdrop on the first popover will appear so that the screen does not get progressively darker as you open more popovers.

You can use the dismissOnSelect property to automatically close the popover when the popover content has been clicked. This behavior does not apply when clicking a trigger element for another popover.

note

Nested popovers cannot be created when using the popoverController because the popover is automatically added to the root of your application when the create method is called.

Interfaces

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

interface PopoverOptions {
  component: any;
  componentProps?: { [key: string]: any };
  showBackdrop?: boolean;
  backdropDismiss?: boolean;
  translucent?: boolean;
  cssClass?: string | string[];
  event?: Event;
  animated?: boolean;

  mode?: 'ios' | 'md';
  keyboardClose?: boolean;
  id?: string;
  htmlAttributes?: { [key: string]: any };

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;

  size?: PopoverSize;
  dismissOnSelect?: boolean;
  reference?: PositionReference;
  side?: PositionSide;
  alignment?: PositionAlign;
  arrow?: boolean;
}

Types

Below you will find all of the custom types for ion-popover:

type PopoverSize = 'cover' | 'auto';
type TriggerAction = 'click' | 'hover' | 'context-menu';
type PositionReference = 'trigger' | 'event';
type PositionSide = 'top' | 'right' | 'bottom' | 'left' | 'start' | 'end';
type PositionAlign = 'start' | 'center' | 'end';

Accessibility

ion-popover has basic keyboard support for navigating between focusable elements inside of the popover. The following table details what each key does:

Key	Function
`Tab`	Moves focus to the next focusable element.
`Shift` + `Tab`	Moves focus to the previous focusable element.
`Esc`	Closes the popover.
`Space` or `Enter`	Clicks the focusable element.

ion-popover has full arrow key support for navigating between ion-item elements with the button property. The most common use case for this is as a dropdown menu in a desktop-focused application. In addition to the basic keyboard support, the following table details arrow key support for dropdown menus:

Key	Function
`ArrowUp`	Moves focus to the previous focusable element.
`ArrowDown`	Moves focus to the next focusable element.
`Home`	Moves focus to the first focusable element.
`End`	Moves focus to the last focusable element.
`ArrowLeft`	When used in a child popover, closes the popover and returns focus to the parent popover.
`Space`, `Enter`, and `ArrowRight`	When focusing a trigger element, opens the associated popover.

Performance

Mounting Inner Contents

The content of an inline ion-popover is unmounted when closed. If this content is expensive to render, developers can use the keepContentsMounted property to mount the content as soon as the popover is mounted. This can help optimize the responsiveness of your application as the inner contents will have already been mounted when the popover opens.

Developers should keep the following in mind when using keepContentsMounted:

This feature should be used as a last resort in order to deal with existing performance problems. Try to identify and resolve performance bottlenecks before using this feature. Additionally, do not use this to anticipate performance problems.
This feature is only needed when using a JavaScript Framework. Developers not using a framework can pass the contents to be rendered into the popover, and the contents will be rendered automatically.
This feature only works with inline popovers. Popovers created with the popoverController are not created ahead of time, so the inner contents are not created either.
Any JavaScript Framework lifecycle hooks on the inner component will run as soon as the popover is mounted, not when the popover is presented.

Properties

alignment

Description	ポップオーバーのコンテンツを `reference` ポイントに揃える方法を記述します。デフォルトは `ios` modeでは `'center'` で、`md` modeでは `'start'` です。
Attribute	`alignment`
Type	`"center" ｜ "end" ｜ "start" ｜ undefined`
Default	`undefined`

animated

Description	`true`の場合、ポップオーバーはアニメーションを行います。
Attribute	`animated`
Type	`boolean`
Default	`true`

arrow

Description	`true`の場合、`ios` modeで動作しているとき、ポップオーバーは `reference` を指し示す矢印を表示します。 `md` modeでは適用されない。
Attribute	`arrow`
Type	`boolean`
Default	`true`

backdropDismiss

Description	`true`の場合、バックドロップがクリックされたときにポップオーバーが解除される。
Attribute	`backdrop-dismiss`
Type	`boolean`
Default	`true`

component

Description	ポップオーバーの内側に表示するコンポーネントです。これを使う必要があるのは、JavaScriptフレームワークを使用していない場合だけです。そうでない場合は、`ion-popover`の中にコンポーネントを入れるだけでいいです。
Attribute	`component`
Type	`Function ｜ HTMLElement ｜ null ｜ string ｜ undefined`
Default	`undefined`

componentProps

Description	ポップオーバー・コンポーネントに渡すデータです。これを使う必要があるのは、JavaScriptフレームワークを使用していない場合だけです。そうでなければ、コンポーネントに直接propsを設定すればよいのです。
Attribute	`undefined`
Type	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

dismissOnSelect

Description	`true`の場合、コンテンツがクリックされると、ポップオーバーは自動的に解除される。
Attribute	`dismiss-on-select`
Type	`boolean`
Default	`false`

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	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

isOpen

Description	`true`の場合、ポップオーバーは開く。もし `false` ならば、ポップオーバーは閉じます。より細かく表示を制御する必要がある場合はこれを使用し、そうでない場合は popoverController または `trigger` プロパティを使用します。注意: ポップオーバーが閉じると `isOpen` は自動的に `false` に戻されません。あなたのコードでそれを行う必要があります。
Attribute	`is-open`
Type	`boolean`
Default	`false`

keepContentsMounted

Description	`true`の場合、ポップオーバーの作成時に `ion-popover` に渡されたコンポーネントが自動的にマウントされます。このコンポーネントは、ポップオーバーが削除されてもマウントされたままです。ただし、ポップオーバーが破棄されると、コンポーネントは破棄されます。このプロパティはリアクティブではないので、ポップオーバーを最初に作成するときにのみ使用する必要があります。注：この機能は、Angular、React、VueなどのJavaScriptフレームワークのインラインポップオーバーにのみ適用されます。
Attribute	`keep-contents-mounted`
Type	`boolean`
Default	`false`

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`

reference

Description	ポップオーバーを何に対して相対的に配置するかを記述します。もし `'trigger'` ならば、ポップオーバーはトリガーボタンに相対して配置されます。イベントを渡すと、event.targetで決定されます。もし `'event'` ならば、ポップオーバーはトリガーアクションのx/y座標に相対的に配置されます。イベントを渡す場合、これはevent.clientXとevent.clientYを介して決定されます。
Attribute	`reference`
Type	`"event" ｜ "trigger"`
Default	`'trigger'`

showBackdrop

Description	`true`の場合、ポップオーバーの後ろに背景が表示されます。このプロパティは、ポップオーバーが表示されたときに背景が画面を暗くするかどうかを制御します。このプロパティは、背景がアクティブであるかどうか、またはDOMに存在するかどうかを制御しません。
Attribute	`show-backdrop`
Type	`boolean`
Default	`true`

side

Description	ポップオーバーを `reference` ポイントのどちら側に配置するかを記述します。start'`と`end' `は RTL を意識した値で、`left'`と`right'` はそうでない値です。
Attribute	`side`
Type	`"bottom" ｜ "end" ｜ "left" ｜ "right" ｜ "start" ｜ "top"`
Default	`'bottom'`

size

Description	ポップオーバーの幅を計算する方法を説明します。cover' `の場合、ポップオーバーの幅はトリガーの幅と一致します。auto'` の場合、ポップオーバーの幅はポップオーバー内のコンテンツによって決定されます。
Attribute	`size`
Type	`"auto" ｜ "cover"`
Default	`'auto'`

translucent

Description	`true`の場合、ポップオーバーは半透明になります。modeが `"ios"` で、デバイスが `backdrop-filter` をサポートしている場合にのみ適用されます。
Attribute	`translucent`
Type	`boolean`
Default	`false`

trigger

Description	ポップオーバーを開かせるトリガー要素に対応するIDです。trigger-action`プロパティを使用して、ポップオーバーを開くためのインタラクションをカスタマイズすることができます。
Attribute	`trigger`
Type	`string ｜ undefined`
Default	`undefined`

triggerAction

Description	どのようなトリガーとの相互作用でポップオーバーを開くべきかを記述します。trigger`プロパティが` undefined `の場合は適用されません。click'` の場合、トリガーが左クリックされたときにポップオーバーが表示されます。hover' `の場合、ポインタがトリガーの上に乗ったときにポップオーバーが表示されます。コンテキストメニュー'`の場合、デスクトップでは右クリック、モバイルでは長押しでポップオーバーが表示されます。これは、デバイスの通常のコンテキストメニューが表示されるのを防ぐことにもなります。
Attribute	`trigger-action`
Type	`"click" ｜ "context-menu" ｜ "hover"`
Default	`'click'`

Events

Name	Description
`didDismiss`	ポップオーバーが解散した後に発行されます。ionPopoverDidDismissの略記です。
`didPresent`	ポップオーバーが提示された後に発行されます。ionPopoverWillDismissの略記です。
`ionPopoverDidDismiss`	ポップオーバーが解除された後に発行されます。
`ionPopoverDidPresent`	ポップオーバーが表示された後に発行されます。
`ionPopoverWillDismiss`	ポップオーバーが解除される前に発行されます。
`ionPopoverWillPresent`	ポップオーバーが表示される前に発行されます。
`willDismiss`	ポップオーバーが解散する前に発行されます。ionPopoverWillDismissの略記です。
`willPresent`	ポップオーバーが提示される前に発行されます。ionPopoverWillPresentの略記です。

Methods

dismiss

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

onDidDismiss

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

onWillDismiss

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

present

Description	ポップオーバーが作成された後に、ポップオーバーを表示します。開発者は、マウス、タッチ、またはポインタイベントを渡すことで、そのイベントがディスパッチされた場所と相対的にポップオーバーを配置することができます。
Signature	`present(event?: MouseEvent ｜ TouchEvent ｜ PointerEvent ｜ CustomEvent) => Promise<void>`

CSS Shadow Parts

Name	Description
`arrow`	参照要素を指し示す矢印。`ios` mode時のみ適用される。
`backdrop`	ion-backdrop`要素です。
`content`	デフォルトslotのラッパー要素です。

CSS Custom Properties

Name	Description
`--backdrop-opacity`	背景の不透明度
`--background`	ポップオーバーの背景
`--box-shadow`	ポップオーバーのボックスシャドウ
`--height`	ポップオーバーの高さ
`--max-height`	ポップオーバーの最大の高さ
`--max-width`	ポップオーバーの最大幅
`--min-height`	ポップオーバーの高さの最小値
`--min-width`	ポップオーバーの最小幅
`--offset-x`	ポップオーバーをX軸方向に移動させる量
`--offset-y`	ポップオーバーをY軸方向に移動させる量を指定します。
`--width`	ポップオーバーの幅

Slots

Name	Description
``	コンテンツは `.popover-content` 要素の内部に配置される。

Inline Popovers​

When to use​

Angular​

Triggers​

note

isOpen Property​

Controller Popovers​

When to use​

React​

Usage​

Styling​

note

Positioning​

Reference​

Side​

Alignment​

Side and Alignment Demo​

Offsets​

Sizing​

Nested Popovers​

note

Interfaces​

Types​

Accessibility​

Keyboard Navigation​

Performance​

Mounting Inner Contents​

Properties​

alignment​

animated​

arrow​

backdropDismiss​

component​

componentProps​

dismissOnSelect​

enterAnimation​

event​

htmlAttributes​

isOpen​

keepContentsMounted​

keyboardClose​

leaveAnimation​

mode​

reference​

showBackdrop​

side​

size​

translucent​

trigger​

triggerAction​

Events​

Methods​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS Shadow Parts​

CSS Custom Properties​

Slots​

Contents

Inline Popovers

When to use

Angular

Triggers

isOpen Property

Controller Popovers

When to use

React

Usage

Styling

Positioning

Reference

Side

Alignment

Side and Alignment Demo

Offsets

Sizing

Nested Popovers

Interfaces

Types

Accessibility

Keyboard Navigation

Performance

Mounting Inner Contents

Properties

alignment

animated

arrow

backdropDismiss

component

componentProps

dismissOnSelect

enterAnimation

event

htmlAttributes

isOpen

keepContentsMounted

keyboardClose

leaveAnimation

mode

reference

showBackdrop

side

size

translucent

trigger

triggerAction

Events

Methods

dismiss

onDidDismiss

onWillDismiss

present

CSS Shadow Parts

CSS Custom Properties

Slots