ons-popover

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.

Tutorial

Popover

A popover can be used to give additional information about a component or add extra functionality.

The usage is very similar to that of <ons-dialog> and <ons-alert-dialog>. It is defined using the <ons-popover> tag:

<ons-popover var="popover">
  This is a popover!
</ons-popover>

var attribute is used to store the popover in a variable for later access.

It is hidden by default and usually attached directly to the <body> tag.

Displaying a popover

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.

Loading from a template

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

For AngularJS, an extra parameter can be passed to specify the scope of the new popover: ons.createElement('popover.html', { parentScope: $scope });

The cancelable attribute

The <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>

See also

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 "up", "down", "left" and "right".

Optional.
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.
var String Variable name to refer this popover. Optional. Works only during initialization.
ons-preshow Expression Allows you to specify custom behavior when the “preshow” event is fired. Optional. Works only during initialization.
ons-prehide Expression Allows you to specify custom behavior when the “prehide” event is fired. Optional. Works only during initialization.
ons-postshow Expression Allows you to specify custom behavior when the “postshow” event is fired. Optional. Works only during initialization.
ons-posthide Expression Allows you to specify custom behavior when the “posthide” event is fired. Optional. Works only during initialization.
ons-destroy Expression Allows you to specify custom behavior when the “destroy” event is fired. Optional. Works only during initialization.
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)”.
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.
on(eventName, listener) Add an event listener.
once(eventName, listener) Add an event listener that’s only triggered once.
off(eventName, [listener]) Remove an event listener. If the listener is not specified all listeners for the event type will be removed.
show(target, [options]): Promise

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

Parameters
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.
hide([options]): Promise

Close the popover.

Returns: Resolves to the hidden element

Parameters
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.
on(eventName, listener)

Add an event listener.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.
once(eventName, listener)

Add an event listener that’s only triggered once.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.
off(eventName, [listener])

Remove an event listener. If the listener is not specified all listeners for the event type will be removed.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.

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.
preshow

Fired just before the popover is displayed.

Parameters
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.
postshow

Fired just after the popover is displayed.

Parameters
Name Type Description
event Object Event object.
event.popover Object Component object.
prehide

Fired just before the popover is hidden.

Parameters
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.
posthide

Fired just after the popover is hidden.

Parameters
Name Type Description
event Object Event object.
event.popover Object Component object.
dialogcancel

Fired when the popover is canceled.

Parameters
Name Type Description

Need Help?

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.