A component that displays a popover next to an element. The popover can be used to display extra information about a component or a tooltip.
To use the element it can either be attached directly to the <body> element or dynamically created from a template using the ons.createPopover(template) utility function and the <template> tag.
Another common way to use the popover is to display a menu when a button on the screen is tapped. For Material Design, popover looks exactly as a dropdown menu.
A popover can be used to give additional information about a component or add extra functionality. In Material Design it looks like a toolbar menu or a dropdown.
The usage is very similar to that of <ons-dialog> and <ons-alert-dialog>. It is defined using the <ons-popover> tag:
<ons-popover>
This is a popover!
</ons-popover>
It is hidden by default and usually attached directly to the <body> tag.
To display the popover you need to get a reference to the element and execute the show(target, options) method. The target argument can be either a DOM element, a query selector string or an Event object.
Just like the <ons-dialog> and <ons-alert-dialog> elements the popover can be loaded from a template. It is done by using the ons.createElement(template) utility function. It returns a Promise that resolves to the popover element.
<template id="popover.html">
<ons-popover>
This popover is defined as a template.
</ons-popover>
</template>
ons
.createElement('popover.html', { append: true })
.then(function(popover) {
popover.show();
});
<ons-popover> supports the cancelable attribute. This enables hiding the popover when the user taps outside of it or presses the back button on an Android device.
<ons-popover cancelable>
This popover can be cancelled!
</ons-popover>
Attributes are added directly to the element. You can do this in HTML or JS.
HTML: <ons-popover someAttribute="true" anotherAttribute><ons-popover>
JS: document.querySelector('ons-popover').setAttribute('someAttribute', 'true')
| Name | Type | Description |
|---|---|---|
| modifier | String | The appearance of the popover. Optional. |
| direction | String |
A space separated list of directions. If more than one direction is specified,
it will be chosen automatically. Valid directions are |
| cancelable | If this attribute is set the popover can be closed by tapping the background or by pressing the back button. Optional. | |
| cover-target | If set the popover will cover the target on the screen. Optional. | |
| target | String | Specifies the ID of the default element for the popover. Optional. |
| animation | String |
The animation used when showing an hiding the popover. Can be either "none", "default", "fade-ios" or "fade-md".
Optional.
|
| animation-options | Expression |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
Optional.
|
| mask-color | Color |
Color of the background mask. Default is "rgba(0, 0, 0, 0.2)".
Optional.
|
| visible | Boolean | Whether the popover is visible or not. Optional. |
Properties are accessed on the element through JS, and should be get and set directly. For example: document.querySelector('ons-popover').coverTarget.
| Name | Description |
|---|---|
| coverTarget | If set the popover will cover the target on the screen. |
| target | Specifies the ID of the default element for the popover. |
| animationOptions |
Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
|
| visible | Whether the element is visible or not. |
| cancelable |
A boolean value that specifies whether the popover is cancelable or not. When the popover is cancelable it can be closed by tapping the background or by pressing the back button on Android devices. |
| onDeviceBackButton | Back-button handler. |
| maskColor | Color of the background mask. Default is “rgba(0, 0, 0, 0.2)”. |
These methods are called directly on the DOM element. Get a reference to the element in JS, and the methods below will be available to call on it. For example: document.querySelector('ons-popover').someMethod().
| Signature | Description |
|---|---|
| show(target, [options]) | Open the popover and point it at a target. The target can be either an event, a CSS selector or a DOM element.. |
| hide([options]) | Close the popover. |
Open the popover and point it at a target. The target can be either an event, a CSS selector or a DOM element..
Returns: Resolves to the displayed element
| Name | Type | Description |
|---|---|---|
| target | String|Event|HTMLElement | Target element. Can be either a CSS selector, an event object or a DOM element. It can be also provided as ‘options.target’ instead. |
| options | Object | Parameter object. |
| options.animation | String |
Animation name. Use one of "fade-ios", "fade-md", "none" and "default".
|
| options.animationOptions | String |
Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
|
| options.callback | Function | This function is called after the popover has been revealed. |
Close the popover.
Returns: Resolves to the hidden element
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.animation | String |
Animation name. Use one of "fade-ios", "fade-md", "none" and "default".
|
| options.animationOptions | String |
Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
|
| options.callback | Function | This functions is called after the popover has been hidden. |
To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-popover').addEventListener('preshow', function() { ... }).
Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).
| Name | Description |
|---|---|
| preshow | Fired just before the popover is displayed. |
| postshow | Fired just after the popover is displayed. |
| prehide | Fired just before the popover is hidden. |
| posthide | Fired just after the popover is hidden. |
| dialogcancel | Fired when the popover is canceled. |
Fired just before the popover is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.popover | Object | Component object. |
| event.cancel | Function | Call this function to stop the popover from being shown. |
Fired just after the popover is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.popover | Object | Component object. |
Fired just before the popover is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.popover | Object | Component object. |
| event.cancel | Function | Call this function to stop the popover from being hidden. |
Fired just after the popover is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.popover | Object | Component object. |
Fired when the popover is canceled.
| Name | Type | Description |
|---|
If you have any questions, use our Community Forum or talk to us on Discord chat. The Onsen UI team and your peers in the community will work together to help solve your issues.
For bug reports and feature requests use our GitHub Issues page.