ons-back-button

Back button component for <ons-toolbar>. Put it in the left part of the <ons-toolbar>. It will find the parent <ons-navigator> element and pop a page when clicked. This behavior can be overriden by specifying the onClick property and calling event.preventDefault in its callback.

Tutorial

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.

See also

Name Type Description
modifier String The appearance of the back button. Optional.
Name Description
options Options object.
options.animation

Animation name. Available animations are “slide”, “lift”, “fade” and “none”. These are platform based animations. For fixed animations, add “-ios” or “-md” suffix to the animation name. E.g. “lift-ios”, “lift-md”. Defaults values are “slide-ios” and “fade-md”.

options.animationOptions Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}
options.callback Function that is called when the transition has ended.
onClick Used to override the default back button behavior.
Name Description
material Material Design style

Need Help?

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.