Menu hamburger icon

Swipe to pop is now available! - Onsen UI 2.5.0

Onsen UI

The Onsen UI team has been working to provide you with exciting new features at every new release. Behold as here come some more!

In this article we introduce the features added in recent versions 2.4.0 and 2.5.0:

  • Swipe to pop (2.5.0)
  • Native <template> Support (2.4.0)
  • <script> in <ons-page> and Page Lifecycle Hooks (2.4.0)
  • Caching / Preloading External Templates (2.4.0)

Swipe to pop (2.5.0)

In Onsen UI 2.5.0 and above, you can use swipe to pop feature by attaching swipeable attribute to <ons-navigator>. This feature enables the popping of pages by swiping the left edge of a page instead of pushing a back button, a common behavior in native iOS.

See the Pen Onsen UI 2.5.0 - Swipe to pop by Naoki Matagawa (@asial-matagawa) on CodePen.

There are two additional options for controlling swipe to pop: swipe-target-width and swipe-threshold attributes.

The swipe-target-width attribute defines the area which accepts the swipe event for swipe to pop. Set a positive pixel value for this attribute (default: 20px).

The swipe-threshold attribute adjusts how much do users have to swipe the page in order to pop it. You can set floating points between 0 and 1.0 (default: 0.2).

Here is an example usage of swipe-target-width and swipe-threshold attributes:

See the Pen Onsen UI 2.5.0 - Swipe to pop - swipe-target-width & swipe-threshold by Naoki Matagawa (@asial-matagawa) on CodePen.

Note that swipe to pop is disabled in the Android version of <ons-navigator> by default because the Material Design does not include that feature.

If you want to enable swipe to pop in the Material version of <ons-navigator> anyway just use swipeable="force". In that case, please keep in mind that you should use slide-md animation since other animations such as lift-md (default value) lead to a weird behavior.

See the Pen Onsen UI 2.5.0 - Swipe to pop - swipeable=”force” in Material Design by Naoki Matagawa (@asial-matagawa) on CodePen.

If you are using AngularJS 1.x binding or Angular 2+ binding, you can just use swipeable, swipe-target-width and swipe-threshold attributes as same as the examples above.

If you are using React binding with <Navigator>, you can just use swipeable, swipe-target-width and swipe-threshold props but in the case of <RouterNavigator> you have to use an additional swipePop prop according to this example.

If you are using Vue binding, you can just attach swipeable, swipe-target-width and swipe-threshold to the <v-ons-navigator> component.

Native <template> Support (2.4.0)

As we show above in the examples of swipe to pop, Onsen UI 2.4.0 and above has support for native <template> element.

<template id="page1.html">
  <ons-page>
    <ons-toolbar>
      <div class="center">Page</div>
    </ons-toolbar>
    <div class="background"></div>
    <div class="content">
      <p>Content here</p>
    </div>
  </ons-page>
</template>

<template> element can be used in Android 4.4+ and iOS 9.0+.

The <ons-template> element is still available for backward compatibility, but there is no advantage in using it. Therefore, we recommend that you use <template> elements if you are planning to create new Onsen UI apps.

<script> in <ons-page> and Page Lifecycle Hooks (2.4.0)

In Onsen UI 2.4.0 and above you can directly write JS statements which are invoked when <ons-page> is appended into the DOM tree by embedding a <script> elements inside the <ons-page> element. Also, new properties onInit, onShow, onHide and onDestroy are now available. Combining these new features, let’s check an example of how to define the layout and behavior of a page:

See the Pen Onsen UI 2.4.0 - <script> in <ons-page> by Naoki Matagawa (@asial-matagawa) on CodePen.

Note that you have to put at most one <script> element just under the <ons-page> element. Also, you have to use <template> instead of <ons-template> if you want to grab the <ons-page> in page templates. If you put your <script> element in <ons-template> it runs before the template is appended into the DOM tree by navigators or splitters.

Caching / Preloading External Templates (2.4.0)

As you may know methods like ons-navigator#pushPage, ons-splitter-content#load and a few others need to load external files. However sending HTTP requests to the same external file multiple times leads to performance degration.

To deal with this problem, Onsen UI 2.4.0 and above caches external files once they are loaded.

But a problem still exists. If we send a first HTTP request to an external file at the timing of pushPage or load, it causes a performance problem in environments that have a slow network or slow servers. So Onsen UI 2.4.0 and above provides ons.preload function which enables you to send HTTP requests to external files ahead of time.

You can use ons.preload function as shown below. ons.preload is an asynchronous function and its Promise resolves after loading the external files.

<head>
  ...
  <script src="onsenui.js"></script>
  <script>
    ons.preload([
      'page2.html', // You can preload multiple files at a time
      'page3.html',
      'page4.html'
    ])
    .then(function(){
      console.log('All external files have been preloaded');
    })
    .catch(function(){
      console.error('Failed to preload external templates');
    });
  </script>
</head>
<body>
  <ons-navigator id="nav" page="page1.html">
  </ons-navigator>

  <template id="page1.html">
    <ons-page>
      <ons-toolbar>
        <div class="center">Page 1</div>
      </ons-toolbar>

      <!-- `pushPage` causes no HTTP request since page2.html is preloaded -->
      <ons-button
        onclick="document.getElementById('nav').pushPage('page2.html')">
        Next Page
      </ons-button>
    </ons-page>
  </template>
</body>

Of cource ons.preload function is not required to be placed in <head> element. You can use this function wherever you prefer.


Onsen UI is an open source library used to create the user interface of hybrid apps. You can find more information on our GitHub page. If you like Onsen UI, please don’t forget to give us a star! ★★★★★

Comments