v-ons-back-button

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

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.

Basic usage

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);

Optionally, v-for directive can be used to iterate over the array and provide direct children. This way, it is possible to pass down extra props to the pages if necessary. This is useful, for example, if we want to pass the page stack down to every page instead of using custom events.

<v-ons-navigator :page-stack="pageStack">
  <component :v-for="page in pageStack" :is="page"
    :page-stack="pageStack"
    :extra-prop=""
    @customEvent=""
  ></component>
</v-ons-navigator>

If our pages implement pageStack prop, it will now be possible to run this.pageStack.push(newPage), for example. Note that passing pageStack prop to VOnsNavigator is still mandatory since it will be used by the VOnsBackButton component.

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)"></v-ons-back-button>

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

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>

For iOS’ “swipe to pop” feature, add the swipeable prop. Note that this behavior is automatically removed on Android platforms unless swipeable="force" is specified.

See also

Props

Name Type Default Value Description
modifier String The appearance of the back button. Optional.

Preset Modifiers

Name Description
material Material Design style

Events Summary

Name Description
click Normal click event. Useful to modify the component default action (pop 1 page).

Events

click

Normal click event. Useful to modify the component default action (pop 1 page).

Parameters
Name Type Description
event Object Event object.
event.preventDefault Function Avoids the default behavior.

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.