ons-navigator

A component that provides page stack management and navigation. Stack navigation is the most common navigation pattern for mobile apps. When a page is pushed on top of the stack it is displayed with a transition animation. When the user returns to the previous page the top page will be popped from the top of the stack and hidden with an opposite transition animation.

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
page String First page to show when navigator is initialized. Optional. Works only during initialization.
swipeable Boolean Enable iOS “swipe to pop” feature. Optional.
swipe-target-width String
20px
The width of swipeable area calculated from the edge (in pixels). Use this to enable swipe only when the finger touch on the screen edge. Optional.
swipe-threshold Number
0.2
Specify how much the page needs to be swiped before popping. A value between 0 and 1. Optional.
animation String
default

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" depending on the platform.

Optional.
animation-options Expression Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'} Optional.
var String Variable name to refer this navigator. Optional. Works only during initialization.
ons-prepush Expression Allows you to specify custom behavior when the “prepush” event is fired. Optional. Works only during initialization.
ons-prepop Expression Allows you to specify custom behavior when the “prepop” event is fired. Optional. Works only during initialization.
ons-postpush Expression Allows you to specify custom behavior when the “postpush” event is fired. Optional. Works only during initialization.
ons-postpop Expression Allows you to specify custom behavior when the “postpop” event is fired. Optional. Works only during initialization.
ons-init Expression Allows you to specify custom behavior when a page’s “init” event is fired. Optional. Works only during initialization.
ons-show Expression Allows you to specify custom behavior when a page’s “show” event is fired. Optional. Works only during initialization.
ons-hide Expression Allows you to specify custom behavior when a page’s “hide” event is fired. Optional. Works only during initialization.
ons-destroy Expression Allows you to specify custom behavior when a page’s “destroy” event is fired. Optional. Works only during initialization.
Name Description
animationOptions Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'}
pageLoader PageLoader instance. It can be overriden to change the way pages are loaded by this element. Useful for lib developers.
page Specify the page to be loaded during initialization. This value takes precedence over the page attribute. Useful for lib developers.
onDeviceBackButton Back-button handler.
topPage Current top page element. Use this method to access options passed by pushPage()-like methods.
pages Copy of the navigator’s page stack.
onSwipe Hook called whenever the user slides the navigator (swipe-to-pop). It gets a decimal ratio (0-1) and an animationOptions object as arguments.
options Default options object. Attributes have priority over this property.
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.
Signature Description
popPage([options]) Pops the current page from the page stack. The previous page will be displayed.
pushPage(page, [options]) Pushes the specified page into the stack.
replacePage(page, [options]) Replaces the current top page with the specified one. Extends pushPage() parameters.
insertPage(index, page, [options]) Insert the specified page into the stack with at a position defined by the index argument. Extends pushPage() parameters.
removePage(index, [options]) Remove the specified page at a position in the stack defined by the index argument. Extends popPage() parameters.
resetToPage(page, [options]) Clears page stack and adds the specified page to the stack. Extends pushPage() parameters.
bringPageTop(item, [options]) Brings the given page to the top of the page stack if it already exists or pushes it into the stack if doesn’t. Extends pushPage() parameters.
on(eventName, listener) Add an event listener.
once(eventName, listener) Add an event listener that’s only triggered once.
off(eventName, [listener]) Remove an event listener. If the listener is not specified all listeners for the event type will be removed.
popPage([options]): Promise

Pops the current page from the page stack. The previous page will be displayed.

Returns: Promise which resolves to the revealed page.

Parameters
Name Type Description
options Object Parameter object.
options.animation String

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 String Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
options.callback Function Function that is called when the transition has ended.
options.data Object Custom data that will be stored in the new page element.
options.times Number Number of pages to be popped. Only one animation will be shown.
pushPage(page, [options]): Promise

Pushes the specified page into the stack.

Returns: Promise which resolves to the pushed page.

Parameters
Name Type Description
page String Page URL. Can be either a HTML document or a template defined with the <template> tag.
options Object Parameter object.
options.page String Page URL. Only necessary if page parameter is null or undefined.
options.pageHTML String HTML code that will be computed as a new page. Overwrites page parameter.
options.animation String

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 String Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}
options.callback Function Function that is called when the transition has ended.
options.data Object Custom data that will be stored in the new page element.
replacePage(page, [options]): Promise

Replaces the current top page with the specified one. Extends pushPage() parameters.

Returns: Promise which resolves to the new page.

insertPage(index, page, [options]): Promise

Insert the specified page into the stack with at a position defined by the index argument. Extends pushPage() parameters.

Returns: Promise which resolves to the inserted page.

Parameters
Name Type Description
index Number The index where it should be inserted.
removePage(index, [options]): Promise

Remove the specified page at a position in the stack defined by the index argument. Extends popPage() parameters.

Returns: Promise which resolves to the revealed page.

Parameters
Name Type Description
index Number The index where it should be removed.
resetToPage(page, [options]): Promise

Clears page stack and adds the specified page to the stack. Extends pushPage() parameters.

Returns: Promise which resolves to the new top page.

Parameters
Name Type Description
options.pop Boolean Performs ‘pop’ effect if true instead of ‘push’ or none. This also sets options.animation value to default instead of none.
bringPageTop(item, [options]): Promise

Brings the given page to the top of the page stack if it already exists or pushes it into the stack if doesn’t. Extends pushPage() parameters.

Returns: Promise which resolves to the new top page.

Parameters
Name Type Description
item String|Number Page URL or index of an existing page in navigator’s stack.
on(eventName, listener)

Add an event listener.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.
once(eventName, listener)

Add an event listener that’s only triggered once.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.
off(eventName, [listener])

Remove an event listener. If the listener is not specified all listeners for the event type will be removed.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.

Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).

Name Description
prepush Fired just before a page is pushed.
prepop Fired just before a page is popped.
postpush Fired just after a page is pushed.
postpop Fired just after a page is popped.
swipe Fired whenever the user slides the navigator (swipe-to-pop).
prepush

Fired just before a page is pushed.

Parameters
Name Type Description
event Object Event object.
event.navigator Object Component object.
event.currentPage Object Current page object.
event.cancel Function Call this function to cancel the push.
prepop

Fired just before a page is popped.

Parameters
Name Type Description
event Object Event object.
event.navigator Object Component object.
event.currentPage Object Current page object.
event.cancel Function Call this function to cancel the pop.
postpush

Fired just after a page is pushed.

Parameters
Name Type Description
event Object Event object.
event.navigator Object Component object.
event.enterPage Object Object of the next page.
event.leavePage Object Object of the previous page.
postpop

Fired just after a page is popped.

Parameters
Name Type Description
event Object Event object.
event.navigator Object Component object.
event.enterPage Object Object of the next page.
event.leavePage Object Object of the previous page.
event.swipeToPop Object True if the pop was triggered by the user swiping to pop.
event.onsBackButton Object True if the pop was caused by pressing an ons-back-button.
swipe

Fired whenever the user slides the navigator (swipe-to-pop).

Parameters
Name Type Description
event Object Event object.
event.ratio Object Decimal ratio (0-1).
event.animationOptions Object

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.