A global object that’s used in Onsen UI.
| Signature | Description |
|---|---|
| isReady() | Returns true if Onsen UI is initialized. |
| isWebView() | Returns true if running inside Cordova. |
| ready(callback) |
Method used to wait for app initialization. Waits for DOMContentLoaded and deviceready, when necessary, before executing the callback.
|
| setDefaultDeviceBackButtonListener(listener) | Set default handler for device back button. |
| disableDeviceBackButtonHandler() |
Disable device back button event handler. Must be called on ons.ready.
|
| enableDeviceBackButtonHandler() |
Enable device back button event handler. Must be called on ons.ready.
|
| enableAutoStatusBarFill() |
Enable status bar fill feature on iOS7 and above (except for iPhone X). Must be called before ons.ready.
|
| disableAutoStatusBarFill() |
Disable status bar fill feature on iOS7 and above (except for iPhone X). Must be called before ons.ready.
|
| mockStatusBar() |
Creates a static element similar to iOS status bar. Only useful for browser testing. Must be called before ons.ready.
|
| disableAnimations() | Disable all animations. Could be handy for testing and older devices. |
| enableAnimations() | Enable animations (default). |
| disableAutoStyling() | Disable automatic styling. |
| enableAutoStyling() | Enable automatic styling based on OS (default). |
| disableIconAutoPrefix() |
Disable adding fa- prefix automatically to ons-icon classes. Useful when including custom icon packs.
|
| forcePlatformStyling(platform) |
Refresh styling for the given platform. Only useful for demos. Use ons.platform.select(...) instead for development and production.
|
| preload(templatePaths) | Separated files need to be requested on demand and this can slightly delay pushing new pages. This method requests and caches templates for later use. |
| createElement(template, options) | Create a new element from a template. Both inline HTML and external files are supported although the return value differs. |
| createPopover(page, [options]) | Create a popover instance from a template. |
| createDialog(page, [options]) | Create a dialog instance from a template. |
| createAlertDialog(page, [options]) | Create a alert dialog instance from a template. |
| openActionSheet(options) | Shows an instant Action Sheet and lets the user choose an action. |
| resolveLoadingPlaceholder(page) |
If no page is defined for the ons-loading-placeholder attribute it will wait for this method being called before loading the page.
|
| getScriptPage() |
Access the last created page from the current script scope. Only works inside <script></script> tags that are direct children of ons-page element. Use this to add lifecycle hooks to a page.
|
| bootstrap([moduleName, [dependencies]]) |
Initialize Onsen UI. Can be used to load Onsen UI without using the ng-app attribute from AngularJS.
|
| findParentComponentUntil(name, [dom]) |
Find parent component object of dom element.
|
| findComponent(selector, [dom]) | Find component object using CSS selector. |
| compile(dom) | Compile Onsen UI components. |
| createElement(template, [options]) |
Create a new element from a template. Both inline HTML and external files are supported although the return value differs. If the element is appended it will also be compiled by AngularJS (otherwise, ons.compile should be manually used).
|
| createAlertDialog(page, [options]) |
Create a alert dialog instance from a template. This method will be deprecated in favor of ons.createElement.
|
| createDialog(page, [options]) |
Create a dialog instance from a template. This method will be deprecated in favor of ons.createElement.
|
| createPopover(page, [options]) |
Create a popover instance from a template. This method will be deprecated in favor of ons.createElement.
|
Returns true if Onsen UI is initialized.
Returns: Will be true if Onsen UI is initialized.
Returns true if running inside Cordova.
Returns: Will be true if the app is running in Cordova.
Method used to wait for app initialization. Waits for DOMContentLoaded and deviceready, when necessary, before executing the callback.
| Name | Type | Description |
|---|---|---|
| callback | Function | Function that executes after Onsen UI has been initialized. |
Set default handler for device back button.
| Name | Type | Description |
|---|---|---|
| listener | Function |
Function that executes when device back button is pressed. Must be called on ons.ready.
|
Disable device back button event handler. Must be called on ons.ready.
Enable device back button event handler. Must be called on ons.ready.
Enable status bar fill feature on iOS7 and above (except for iPhone X). Must be called before ons.ready.
Disable status bar fill feature on iOS7 and above (except for iPhone X). Must be called before ons.ready.
Creates a static element similar to iOS status bar. Only useful for browser testing. Must be called before ons.ready.
Disable all animations. Could be handy for testing and older devices.
Enable animations (default).
Disable automatic styling.
Enable automatic styling based on OS (default).
Disable adding fa- prefix automatically to ons-icon classes. Useful when including custom icon packs.
Refresh styling for the given platform. Only useful for demos. Use ons.platform.select(...) instead for development and production.
| Name | Type | Description |
|---|---|---|
| platform | string |
Separated files need to be requested on demand and this can slightly delay pushing new pages. This method requests and caches templates for later use.
Returns: Promise that resolves when all the templates are cached.
| Name | Type | Description |
|---|---|---|
| templatePaths | String|Array | Set of HTML file paths containing ‘ons-page’ elements. |
Create a new element from a template. Both inline HTML and external files are supported although the return value differs.
Returns: If the provided template was an inline HTML string, it returns the new element. Otherwise, it returns a promise that resolves to the new element.
| Name | Type | Description |
|---|---|---|
| template | String |
Either an HTML file path, a <template> id or an HTML string such as '<div id="foo">hoge</div>'.
|
| options | Object | Parameter object. |
| options.append | Boolean|HTMLElement |
Whether or not the element should be automatically appended to the DOM. Defaults to false. If true value is given, document.body will be used as the target.
|
| options.insertBefore | HTMLElement |
Reference node that becomes the next sibling of the new node (options.append element).
|
Create a popover instance from a template.
Returns: Promise object that resolves to the popover component object.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or a containing a |
| options | Object | Parameter object. |
| options.parentScope | Object | Parent scope of the dialog. Used to bind models and access scope methods from the dialog. |
Create a dialog instance from a template.
Returns: Promise object that resolves to the dialog component object.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or an <template> containing a |
| options | Object | Parameter object. |
Create a alert dialog instance from a template.
Returns: Promise object that resolves to the alert dialog component object.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or an <template> containing a |
| options | Object | Parameter object. |
Shows an instant Action Sheet and lets the user choose an action.
Returns: Will resolve when the action sheet is closed. The resolve value is either the index of the tapped button or -1 when canceled.
| Name | Type | Description |
|---|---|---|
| options | Object | Parameter object. |
| options.buttons | Array |
Represent each button of the action sheet following the specified order. Every item can be either a string label or an object containing label, icon and modifier properties.
|
| options.title | String | Optional title for the action sheet. |
| options.destructive | Number | Optional index of the “destructive” button (only for iOS). It can be specified in the button array as well. |
| options.cancelable | Boolean | Whether the action sheet can be canceled by tapping on the background mask or not. |
| options.modifier | String |
Modifier attribute of the action sheet. E.g. 'destructive'.
|
| options.maskColor | String | Optionally change the background mask color. |
| options.id | String | The element’s id attribute. |
| options.class | String | The element’s class attribute. |
If no page is defined for the ons-loading-placeholder attribute it will wait for this method being called before loading the page.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or a <template> id.
|
Access the last created page from the current script scope. Only works inside <script></script> tags that are direct children of ons-page element. Use this to add lifecycle hooks to a page.
Returns: Returns the corresponding page element.
Initialize Onsen UI. Can be used to load Onsen UI without using the ng-app attribute from AngularJS.
Returns: An AngularJS module object.
| Name | Type | Description |
|---|---|---|
| moduleName | String | AngularJS module name. |
| dependencies | Array | List of AngularJS module dependencies. |
Find parent component object of dom element.
Returns: Component object. Will return null if no component was found.
| Name | Type | Description |
|---|---|---|
| name | String | Name of component, i.e. ‘ons-page’. |
| dom | Object/jqLite/HTMLElement | $event, jqLite or HTMLElement object. |
Find component object using CSS selector.
Returns: Component object. Will return null if no component was found.
| Name | Type | Description |
|---|---|---|
| selector | String | CSS selector |
| dom | HTMLElement | DOM element to search from. |
Compile Onsen UI components.
| Name | Type | Description |
|---|---|---|
| dom | HTMLElement | Element to compile. |
Create a new element from a template. Both inline HTML and external files are supported although the return value differs. If the element is appended it will also be compiled by AngularJS (otherwise, ons.compile should be manually used).
Returns: If the provided template was an inline HTML string, it returns the new element. Otherwise, it returns a promise that resolves to the new element.
| Name | Type | Description |
|---|---|---|
| template | String |
Either an HTML file path, an <ons-template> id or an HTML string such as '<div id="foo">hoge</div>'.
|
| options | Object | Parameter object. |
| options.append | Boolean|HTMLElement |
Whether or not the element should be automatically appended to the DOM. Defaults to false. If true value is given, document.body will be used as the target.
|
| options.insertBefore | HTMLElement |
Reference node that becomes the next sibling of the new node (options.append element).
|
| options.parentScope | Object | Parent scope of the element. Used to bind models and access scope methods from the element. Requires append option. |
Create a alert dialog instance from a template. This method will be deprecated in favor of ons.createElement.
Returns: Promise object that resolves to the alert dialog component object.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or an |
| options | Object | Parameter object. |
| options.parentScope | Object | Parent scope of the dialog. Used to bind models and access scope methods from the dialog. |
Create a dialog instance from a template. This method will be deprecated in favor of ons.createElement.
Returns: Promise object that resolves to the dialog component object.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or an |
| options | Object | Parameter object. |
| options.parentScope | Object | Parent scope of the dialog. Used to bind models and access scope methods from the dialog. |
Create a popover instance from a template. This method will be deprecated in favor of ons.createElement.
Returns: Promise object that resolves to the popover component object.
| Name | Type | Description |
|---|---|---|
| page | String |
Page name. Can be either an HTML file or an |
| options | Object | Parameter object. |
| options.parentScope | Object | Parent scope of the dialog. Used to bind models and access scope methods from the dialog. |
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.