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:

var myNavigator = document.getElementById('myNavigator');
myNavigator.pushPage('page2.html');

The 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 will be available in the new page element: 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.

Conditional first page

Many apps show a different first page depending on whether the user is logged in or not. To achieve this with the navigator, it is best not to define any page attribute on the navigator element at all. Then, when the app is ready, determine what the first page should be.

ons.ready(function() {
  if(isLoggedIn()) {
    myNavigator.pushPage('homePage.html');
  } else {
    myNavigator.pushPage('loginPage.html');
  }
});