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

Stack navigation

The VOnsNavigator is a component that provides stack based navigation. It is a very common navigation pattern in mobile apps. After pushing a page to the top of the stack, it will be displayed using transition animation. When the user goes back to the previous page the top page will be popped from the top of the stack and hidden with a corresponding transition animation.

An array of VOnsPage components must be passed as a prop to VOnsNavigator.

<v-ons-navigator :page-stack="[p1, p2, p3]"></v-ons-navigator>

Whenever the page stack is modified, VOnsNavigator will perform the corresponding transition. Pushing or popping multiple pages at once is allowed, although only 1 animation will be performed.

Any action will throw corresponding prepush, postpush, prepop and postpop events.

Modifying the stack

The page stack can be modified from any place where the array is accessible either by calling array methods (push, pop, splice…) or assigning a new value (pageStack = [...pageStack, newPage]). This “pageStack” can be created at any component level but it must be passed to v-ons-navigator as a prop.

For example, if there is a VOnsSplitter as a parent component of VOnsNavigator that also needs to modify the stack, the splitter will create the array and then pass it to the child navigator. This way, both components (parent splitter and child navigator) will be able to modify the stack.

In order to push a new page from the current one (sibling pages), pages must have access to the stack array as well. There are many ways to achieve this sort of component communication in Vue. First one, we can define custom actions as event listeners:

<v-ons-navigator :page-stack="pageStack"
  @push-page="pageStack.push($event)"
  @replace-page="pageStack.pop(); pageStack.push($event)"
></v-ons-navigator>

VOnsNavigator sets custom listeners (i.e. anything except @prepush, @postpush, @prepop and @postpop) directly to its child pages. This way, you can name your events however you like and do any action you want. With the previous example, we can push a new page from any existing page as follows:

// import newPage from ...
this.$emit('push-page', newPage);

Passing data around

Navigator’s pages are sibling elements, which means that communication among them in Vue is fairly challenging. Vuex is a good solution for this, but not the only one. When you push a new page component and want to add some initial data, you can simply extend it and let Vue merge the new data prop with the original one in newPage component:

this.$emit('push-page', {
  extends: newPage,
  data() {
    myCustomDataHere: 42
  }
});

Alternatively, since 2.5.2 we can also pass props to the pages through the onsNavigatorProps property:

this.$emit('push-page', {
  ...newPage, // Or 'extends: newPage'
  onsNavigatorProps: {
    myCustomPropHere: 42,
    // ...
  }
});

Any props passed using onsNavigatorProps must be defined using props on the extended page, or they will not be available. For example, newPage as used above might look like this:

const newPage = {
  name: 'newPage',
  template: `<v-ons-page>{{myCustomPropHere}}</v-ons-page>`,
  props: {
    myCustomPropHere: {
      type: Number,
      required: true
    }
  }
}

In order to pass data back to the previous page, we can either use Vuex, an event bus, or simply pass a function that modifies the corresponding context. If page A pushes page B, it can send a function as a prop or data (mentioned above) that modifies page A’s context. This way, whenever we want to send anything to page A from page B, the latter just needs to call the function and pass some arguments:

// Page A
this.$emit('push-page', {
  extends: pageB,
  onsNavigatorProps: {
    passDataBack(data) {
      this.dataFromPageB = data;
    }
  }
});

Customizing the animation

There are several animations available for VOnsNavigator component. It can be specified with the options.animation prop. Available animations are slide, lift and fade. Setting the property to none will make the transition instantly.

It is also possible to customize the duration, delay and timing function of the animation using the options.animationOptions property.

<v-ons-navigator
  :options="{
    animation: 'fade',
    animationOptions: {duration: 0.2, timing: 'ease-in'}
  }"
>
</v-ons-navigator>

The same options can be passed through the onsNavigatorOptions property when pushing pages in order to modify only specific pages:

this.$emit('push-page', {
  extends: newPage,
  onsNavigatorOptions: {
    animation: 'lift',
    animationOptions: { duration: 0.5 }
  }
});
`

For iOS’ “swipe to pop” feature, add the swipeable prop. Note that this behavior only works with animations that support this feature, such as slide-ios (default slide animation on iOS).

The back button

The VOnsBackButton component can be used to display a back button in the navigation bar. By default, this component automatically finds its parent VOnsNavigator component and pops a page when pressed. However, this default behavior can be overriden by running event.preventDefault in a click handler (or using Vue’s .prevent shorthand modifier):

<v-ons-back-button
  @click.prevent="pageStack.splice(1, pageStack.length - 1)"
>
  Back
</v-ons-back-button>

The previous code resets the pageStack to its first page instead of popping 1 single page. It assumes pageStack variable exists in the current context.

See also

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

Optional.
options.animationOptions Expression Specify the animation’s duration, timing and delay with an object literal. E.g. {duration: 0.2, delay: 1, timing: 'ease-in'} Optional.
options.callback Function Function that is called when the transition has ended. Optional.
page First page to show when navigator is initialized. Optional.
page-stack Array Array of VOnsPage components that represents VOnsNavigator page stack. Required.
pop-page Defines how VOnsNavigator should pop a page on VOnsBackButton click or Device Back Button event. Defaults to () => this.pageStack.pop(). Useful when the pageStack is located in a store. Optional.
swipe-target-width String 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 Specify how much the page needs to be swiped before popping. A value between 0 and 1. Optional.
swipeable Boolean Enable iOS “swipe to pop” feature. Optional.
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).
deviceBackButton Fired on device back button. Default behavior is popping 1 page when pageStack contains more than 1. Otherwise, calls parent handler.
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
deviceBackButton

Fired on device back button. Default behavior is popping 1 page when pageStack contains more than 1. Otherwise, calls parent handler.

Parameters
Name Type Description
event Object Event object.
event.preventDefault Function Avoids the default behavior.
event.callParentHandler Function Runs the handler for the immediate parent that supports device back button.

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.