$ons

A global object that’s used in Onsen UI.

Methods

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 component 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.
forceUIWebViewScrollFix() Applies a fix for iOS UIWebView which prevents scroll events jumping to pages under the top layer. This may visually affect normal scrolling of UIWebView if you open a dialog/menu before the scroll momentum finished. Disabled by default.
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 component 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 component. Use this to add lifecycle hooks to a page.
isReady(): Boolean

Returns true if Onsen UI is initialized.

Returns: Will be true if Onsen UI is initialized.

isWebView(): Boolean

Returns true if running inside Cordova.

Returns: Will be true if the app is running in Cordova.

ready(callback)

Method used to wait for app initialization. Waits for DOMContentLoaded and deviceready, when necessary, before executing the callback.

Parameters
Name Type Description
callback Function Function that executes after Onsen UI has been initialized.
setDefaultDeviceBackButtonListener(listener)

Set default handler for device back button.

Parameters
Name Type Description
listener Function Function that executes when device back button is pressed. Must be called on $ons.ready.
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 component 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.

forceUIWebViewScrollFix()

Applies a fix for iOS UIWebView which prevents scroll events jumping to pages under the top layer. This may visually affect normal scrolling of UIWebView if you open a dialog/menu before the scroll momentum finished. Disabled by default.

Parameters
Name Type Description
force Boolean
forcePlatformStyling(platform)

Refresh styling for the given platform. Only useful for demos. Use $ons.platform.select(...) instead for development and production.

Parameters
Name Type Description
platform string
preload(templatePaths): Promise

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.

Parameters
Name Type Description
templatePaths String|Array Set of HTML file paths containing ‘ons-page’ components.
createElement(template, options): HTMLElement|Promise

Create a new component 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 component. Otherwise, it returns a promise that resolves to the new component.

Parameters
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 component 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 component).
createPopover(page, [options]): Promise

Create a popover instance from a template.

Returns: Promise object that resolves to the popover component object.

Parameters
Name Type Description
page String Page name. Can be either an HTML file or a