The Navigator

The <ons-navigator> element handles a stack of pages. This is a very common type of navigation in mobile apps where one page is pushed on top of another using a transition animation.

To change the animation you can use the animation attribute:

<ons-navigator animation="fade"></ons-navigator>

Available animations are:

• fade
• lift
• slide
• none

For iOS’ “swipe to pop” feature, add the swipeable attribute. Note that this behavior is automatically removed on Android platforms unless swipeable="force" is specified.

Defining pages

The pages that you push to the Navigator are defined using a <template> element.

<template id="page2.html">
  <ons-page>
    ...
  </ons-page>
</template>

The id attribute is used to reference the pages when pushing.

Pushing pages

To push a new page to the top of the stack, the pushPage(page, options) method is used.

In Onsen UI all such methods are attached to the element so you need to create a reference to it. You can do this by using var attribute:

<ons-navigator var="myNavigator"></ons-navigator>

This will allow you to call Navigator’s method like this: myNavigator.pushPage('page2.html');

pushPage method returns a Promise object that is resolved when the transition is finished. You can try adding the following code:

myNavigator
  .pushPage('page2.html')
  .then(function() {
    ons.notification.alert('Page pushed!');
  });

Sending custom data to a new page

It may be useful to have access to custom data when we push a new page. This is achieved by passing options.data parameter:

myNavigator
  .pushPage('page2.html', {
    data: {
      title: 'New Page',
      // ...
    },
    // Other options
  });

options.data object can be safely accessed after the init event of the new page. ons-init handler can be used to handle this event. It is also possible to access this object from scope functions or views with myNavigator.topPage.data.

Going back

To go back to a previous page the popPage(options) method is used.

Another way is to use the <ons-back-button> element. It can be added to the left side of the toolbar and renders as an arrow:

<ons-toolbar>
  <div class="left">
    <ons-back-button>Back</ons-back-button>
  </div>
</ons-toolbar>

It will automatically find the Navigator element and trigger a popPage() call so there is no need to attach any click handlers to it.