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 used to display some information on top of the app and take the focus. It forbids user interaction with the background.
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.
| 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. |
| var | String | Variable name to refer this modal. 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 |
|---|---|
| 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. |
| 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. |
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.