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.
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.
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 modal.
Returns: Resolves to the displayed element
| 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 modal visibility.
| 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 modal.
Returns: Resolves to the hidden element
| 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. |
Fired just before the modal is displayed.
| 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. |
Fired just after the modal is displayed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.modal | Object | Component object. |
Fired just before the modal is hidden.
| 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. |
Fired just after the modal is hidden.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.modal | Object | Component object. |
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.