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

See also

Attributes

Name Type Default Value Description
page String First page to show when navigator is initialized. Optional. Works only during initialization.
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.

Properties

Name Description
pageLoader
page
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.
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.
options.refresh If this parameter is true, the previous page will be refreshed (destroyed and created again) before popPage() action.

Methods Summary

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.
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.

Events Summary

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.

Methods

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.refresh Boolean The previous page will be refreshed (destroyed and created again) before popPage action.
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.

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 <ons-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.

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.

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.

Events

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.

Discussion

Need Help?

If you have any questions, use our Community Forum or talk to us via Gitter 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.