ons-modal

Modal component that masks current screen. Underlying components are not subject to any events while the modal component is shown. This component can be used to block user input while some operation is running or to show some information to the user.

Tutorial

Modals are very versatible components in Onsen UI. They can be used to display some information on top of the app and take the focus since it forbids user interaction with the background. It can also be used to show temporary pages such as input completion list.

Simply add the modal tags together with the page.

<ons-page>...</ons-page>

<ons-modal>
  This is a modal!
</ons-modal>

Use show, hide and toggle methods to control it.

It can also contain ons-page component and anything else inside it. This way, ons-modal can be used to overlay a page without ons-navigator in a simpler way.

See also

Attributes are added directly to the element. You can do this in HTML or JS.

HTML: <ons-modal someAttribute="true" anotherAttribute><ons-modal>
JS: document.querySelector('ons-modal').setAttribute('someAttribute', 'true')

Name Type Description
animation String
default
The animation used when showing and hiding the modal. Can be either "none", "fade" or "lift". 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.
visible Boolean Whether the modal 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-modal').animationOptions.

Name Description
animationOptions Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}.
onDeviceBackButton Back-button handler.
visible Whether the element is visible or not.

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-modal').someMethod().

Signature Description
show([options]) Show modal.
toggle([options]) Toggle modal visibility.
hide([options]) Hide modal.
show([options]): Promise

Show modal.

Returns: Resolves to the displayed element

Parameters
Name Type Description
options Object Parameter object.
options.animation String Animation name. Available animations are "none" and "fade".
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 modal has been revealed.
toggle([options])

Toggle modal visibility.

Parameters
Name Type Description
options Object Parameter object.
options.animation String Animation name. Available animations are "none" and "fade".
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 modal has been revealed.
hide([options]): Promise

Hide modal.

Returns: Resolves to the hidden element

Parameters
Name Type Description
options Object Parameter object.
options.animation String Animation name. Available animations are "none" and "fade".
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 modal has been revealed.

To use these events, add event listeners to the elements as you would for native events, like click. For example: document.querySelector('ons-modal').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 modal is displayed.
postshow Fired just after the modal is displayed.
prehide Fired just before the modal is hidden.
posthide Fired just after the modal is hidden.
preshow

Fired just before the modal is displayed.

Parameters
Name Type Description
event Object Event object.
event.modal Object Component object.
event.cancel Function Execute this function to stop the modal from being shown.
postshow

Fired just after the modal is displayed.

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

Fired just before the modal is hidden.

Parameters
Name Type Description
event Object Event object.
event.modal Object Component object.
event.cancel Function Execute this function to stop the modal from being hidden.
posthide

Fired just after the modal is hidden.

Parameters
Name Type Description
event Object Event object.
event.modal Object Component object.

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.