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 Popoversion-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. See Usage for an example of how to write a popover inline.
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.
#
AngularSince 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>
:
#
When to useUsing 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
.
#
Controller Popoversion-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. See Usage for an example of how to use the popoverController
.
#
When to useWe 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.
#
InterfacesBelow you will find all of the options available to you when using the popoverController
. These options should be supplied when calling popoverController.create()
.
#
TypesBelow you will find all of the custom types for ion-popover
:
#
CustomizationPopover 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 setting a custom class on the host element if writing a popover inline or supplying a class to the cssClass
option if using the popoverController
and using that to add custom styles to the host and inner elements. The cssClass
option can also accept multiple classes separated by spaces. View the Usage section for an example of how to pass a class using cssClass
.
Any of the defined CSS Custom Properties can be used to style the Popover without needing to target individual elements:
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.
#
TriggersA trigger for an 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. The following example shows how to create a right click menu using trigger
and trigger-action
. Note that trigger-action="context-menu"
will prevent your system's default context menu from opening.
Triggers are not applicable when using the
popoverController
because theion-popover
is not created ahead of time.#
Positioning
#
ReferenceWhen 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.
#
SideRegardless 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.
#
AlignmentThe 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.
#
OffsetsIf 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
.
#
SizingWhen 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.
#
Nested PopoversWhen 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. See the Usage section for an example on how to write a nested popover.
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.
Nested popovers cannot be created when using the
popoverController
because the popover is automatically added to the root of your application when thecreate
method is called.
#
Accessibility#
Keyboard Navigationion-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. |
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. |
#
Usage- ANGULAR
- JAVASCRIPT
- REACT
- STENCIL
- VUE
#
Style PlacementIn 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
.
Developers can also use this component directly in their template:
#
Properties#
alignmentDescription | Describes how to align the popover content with the reference point. |
Attribute | alignment |
Type | "center" \| "end" \| "start" |
Default | 'start' |
#
animatedDescription | If true , the popover will animate. |
Attribute | animated |
Type | boolean |
Default | true |
#
arrowDescription | If true , the popover will display an arrowthat points at the reference when running in ios modeon mobile. Does not apply in md mode or on desktop. |
Attribute | arrow |
Type | boolean |
Default | true |
#
backdropDismissDescription | If true , the popover will be dismissed when the backdrop is clicked. |
Attribute | backdrop-dismiss |
Type | boolean |
Default | true |
#
componentDescription | The component to display inside of the popover. You only need to use this if you are not using a JavaScript framework. Otherwise, you can just slot your component inside of ion-popover . |
Attribute | component |
Type | Function \| HTMLElement \| null \| string \| undefined |
Default | undefined |
#
componentPropsDescription | The data to pass to the popover component. You only need to use this if you are not using a JavaScript framework. Otherwise, you can just set the props directly on your component. |
Attribute | undefined |
Type | undefined \| { [key: string]: any; } |
Default | undefined |
#
dismissOnSelectDescription | If true , the popover will be automaticallydismissed when the content has been clicked. |
Attribute | dismiss-on-select |
Type | boolean |
Default | false |
#
enterAnimationDescription | Animation to use when the popover is presented. |
Attribute | undefined |
Type | ((baseEl: any, opts?: any) => Animation) \| undefined |
Default | undefined |
#
eventDescription | The event to pass to the popover animation. |
Attribute | event |
Type | any |
Default | undefined |
#
isOpenDescription | If true , the popover will open. If false , the popover will close.Use this if you need finer grained control over presentation, otherwise just use the popoverController or the trigger property.Note: isOpen will not automatically be set back to false whenthe popover dismisses. You will need to do that in your code. |
Attribute | is-open |
Type | boolean |
Default | false |
#
keyboardCloseDescription | If true , the keyboard will be automatically dismissed when the overlay is presented. |
Attribute | keyboard-close |
Type | boolean |
Default | true |
#
leaveAnimationDescription | Animation to use when the popover is dismissed. |
Attribute | undefined |
Type | ((baseEl: any, opts?: any) => Animation) \| undefined |
Default | undefined |
#
modeDescription | The mode determines which platform styles to use. |
Attribute | mode |
Type | "ios" \| "md" |
Default | undefined |
#
referenceDescription | Describes what to position the popover relative to. If 'trigger' , the popover will be positioned relativeto the trigger button. If passing in an event, this is determined via event.target. If 'event' , the popover will be positioned relativeto the x/y coordinates of the trigger action. If passing in an event, this is determined via event.clientX and event.clientY. |
Attribute | reference |
Type | "event" \| "trigger" |
Default | 'trigger' |
#
showBackdropDescription | If true , a backdrop will be displayed behind the popover. |
Attribute | show-backdrop |
Type | boolean |
Default | true |
#
sideDescription | Describes which side of the reference point to positionthe popover on. The 'start' and 'end' values are RTL-aware,and the 'left' and 'right' values are not. |
Attribute | side |
Type | "bottom" \| "end" \| "left" \| "right" \| "start" \| "top" |
Default | 'bottom' |
#
sizeDescription | Describes how to calculate the popover width. If 'cover' , the popover width will match the width of the trigger.If 'auto' , the popover width will be determined by the content inthe popover. |
Attribute | size |
Type | "auto" \| "cover" |
Default | 'auto' |
#
translucentDescription | If true , the popover will be translucent.Only applies when the mode is "ios" and the device supportsbackdrop-filter . |
Attribute | translucent |
Type | boolean |
Default | false |
#
triggerDescription | An ID corresponding to the trigger element that causes the popover to open. Use the trigger-action property to customize the interaction that results in the popover opening. |
Attribute | trigger |
Type | string \| undefined |
Default | undefined |
#
triggerActionDescription | Describes what kind of interaction with the trigger that should cause the popover to open. Does not apply when the trigger property is undefined .If 'click' , the popover will be presented when the trigger is left clicked.If 'hover' , the popover will be presented when a pointer hovers over the trigger.If 'context-menu' , the popover will be presented when the trigger is rightclicked on desktop and long pressed on mobile. This will also prevent your device's normal context menu from appearing. |
Attribute | trigger-action |
Type | "click" \| "context-menu" \| "hover" |
Default | 'click' |
#
EventsName | Description |
---|---|
didDismiss | Emitted after the popover has dismissed. |
Shorthand for ionPopoverDidDismiss. | |
didPresent | Emitted after the popover has presented. |
Shorthand for ionPopoverWillDismiss. | |
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. |
willDismiss | Emitted before the popover has dismissed. |
Shorthand for ionPopoverWillDismiss. | |
willPresent | Emitted before the popover has presented. |
Shorthand for ionPopoverWillPresent. |
#
Methods#
dismissDescription | Dismiss the popover overlay after it has been presented. |
Signature | dismiss(data?: any, role?: string \| undefined, dismissParentPopover?: boolean) => Promise<boolean> |
#
onDidDismissDescription | Returns a promise that resolves when the popover did dismiss. |
Signature | onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
#
onWillDismissDescription | Returns a promise that resolves when the popover will dismiss. |
Signature | onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>> |
#
presentDescription | Present the popover overlay after it has been created. |
Signature | present() => Promise<void> |
#
CSS Shadow PartsName | Description |
---|---|
arrow | The arrow that points to the reference element. Only applies on ios mode. |
backdrop | The ion-backdrop element. |
content | The wrapper element for the default slot. |
#
CSS Custom PropertiesName | 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 |
--offset-x | The amount to move the popover by on the x-axis |
--offset-y | The amount to move the popover by on the y-axis |
--width | Width of the popover |
#
SlotsName | Description |
---|---|
`` | Content is placed inside of the .popover-content element. |