v-ons-tabbar

A component to display a tab bar on the bottom of a page. Used with <ons-tab> to manage pages using tabs.

Tutorial

Tabs

The VOnsTabbar component is used to add tab navigation to an app. It is a very common navigation pattern in mobile apps.

The tabs prop includes all the necessary information to render VOnsTab components and their linked VOnsPage components. This prop must be an array of object containing at least one of the next keys: icon, label or page. It can include other optional keys such as activeIcon, badge, active, etc. A special props key can also be provided in order to specify props for the corresponding page.

<v-ons-tabbar
  :tabs="[
    { label: 't1', page: p1 },
    { label: 't2', page: p2, props: { aPageProp: 'hello' } }
  ]"
>
</v-ons-tabbar>

The mentioned tabs prop is the preferred way to provide tabs information to VOnsTabbar, although it is not the only one. It is also possible to provide v-slot:pages and VOnsTab components directly as children instead:

<v-ons-tabbar>
  <template v-slot:pages>
    <home-page></home-page>
    <news-page></news-page>
    <settings-page></settings-page>
  </template>

  <v-ons-tab v-for="(tab, i) in tabs"
    :icon="tabs[i].icon"
    :label="tabs[i].label"
    :badge="tabs[i].badge"
    ></v-ons-tab>
</v-ons-tabbar>

This is a longer version that offers higher control. It can be combined with tabs prop by, for example, providing only VOnsTab-related information (everything except page key) in tabs prop and also v-slot:pages at the same time (the VOnsTab will match page’s DOM index).

Synchronizing :active-index prop

The VOnsTabbar component implements an optional activeIndex prop which is used to specify the page that is currently visible. This component fires update:activeIndex events whenever the user taps on a VOnsTab. This is useful to synchronize the value of index prop and can be directly handled by using Vue’s v-model:activeIndex directive:

<v-ons-tabbar v-model:active-index="tabbarIndex"></v-ons-tabbar>

The activeIndex prop is not completely necessary. If you don’t need to set an active tab in any other way than tapping, then it would be enough to provide active attribute (or key in tabs prop) to the desired VOnsTab in order to set the initial active tab.

The VOnsTab component

VOnsTab components have the following attributes/props:

  • icon: specifies the displayed icon.
  • label: specifies the displayed text label.
  • badge: shows a small badge on top of the tab.
  • activeIcon: allows to change the icon when the tab becomes active.
  • active: Whether the tab should be displayed as active or not. This is not necessary when using activeIndex prop.

Every tab has, by default, the same width. 50% with two tabs, 25% with four tabs and so on. To allow tabs grow depending on their content (i.e. shorter/ longer labels), use the autogrow modifier in v-ons-tabbar component. Optionally, max-width CSS property can be specified to set the width of the tab (for each v-ons-tab).

Swipes and Animations

By default, the tab bar will slide from one page to another on tab click. Use animation="none" attribute to have an instant change.

swipeable attribute can be used to enable this functionality. It can be toggled to allow or prevent swipes at different moments of the app.

These attributes can be combined to have a tab bar with instant changes that can also be swiped:

<v-ons-tabbar swipeable animation="none">...</v-ons-tabbar>

For iOS, tab-border attribute can be included to show a tab border that updates position during swipe (this is always default on Android).

Advanced usage

VOnsTab behavior can be overridden by running event.preventDefault on click event handler.

For example, this can provide fine control to support some of Vue’s cool features:

<v-ons-tabbar>
  <template v-slot:pages>
    <transition>
      <keep-alive>
        <component :is="currentPage"></component>
      </keep-alive>
    </transition>
  </template>

  <v-ons-tab
    @click.prevent="currentPage = 'home'"
    :active="currentPage === 'home'"
  ></v-ons-tab>
  <v-ons-tab
    @click.prevent="currentPage = 'settings'"
    :active="currentPage === 'settings'"
  ></v-ons-tab>
</v-ons-tabbar>

Notice that preventing the default behavior means that VOnsTabbar events (prechange, postchange, reactive…) are not fired. Also, it won’t be swipeable if only 1 page is provided at a time (when using :is="component", for example).

See also

Name Type Description
activeIndex Number The index of the tab that is currently active. Optional.
animation String If this attribute is set to "none" the transitions will not be animated. Optional.
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.
ignoreEdgeWidth Number Distance in pixels from both edges. Swiping on these areas will prioritize parent components such as ons-splitter or ons-navigator. Optional.
modifier String The appearance of the tabbar. Optional.
position String Tabbar’s position. Available values are "bottom" and "top". Use "auto" to choose position depending on platform (bottom for iOS flat design, top for Material Design). Optional.
swipeable Boolean If this attribute is set the tab bar can be scrolled by drag or swipe. Optional.
tabbarStyle Boolean Optional style for the actual tabbar element. Accepts any Vue valid style. Optional.
tabBorder Boolean If this attribute is set the tabs show a dynamic bottom border. Only works for iOS flat design since the border is always visible in Material Design. Optional.
tabs Array Contains as many objects as desired tabs in the tabbar. Every object describes a VOnsTab component. Every object must include at least one of the next properties: page, icon or label (see VOnsTab reference for more options). It is also possible to pass props to the pages through a props object for each tab. Example: tabs: [ { label: 'p1', page: p1 }, { label: 'p2', page: p2, props: { myPage2Prop: 'something' } } ]. This can be omitted if using slot="pages" and slot="tabs" elements. Optional.
visible Boolean Specify the visibility of the component. Optional.
Name Description
material A tabbar in Material Design.
autogrow Tabs automatically grow depending on their content instead of having a fixed width.
top-border Shows a static border-bottom in tabs for iOS top tabbars.
Name Description
prechange Fires just before the tab is changed.
postchange Fires just after the tab is changed.
reactive Fires if the already open tab is tapped again.
swipe Fires when the tabbar swipes.
update:activeIndex Fired right after user interaction. Useful to update activeIndex prop.
prechange

Fires just before the tab is changed.

Parameters
Name Type Description
event Object Event object.
event.index Number Current index.
event.tabItem Object Tab item object.
event.cancel Function Call this function to cancel the change event.
postchange

Fires just after the tab is changed.

Parameters
Name Type Description
event Object Event object.
event.index Number Current index.
event.tabItem Object Tab item object.
reactive

Fires if the already open tab is tapped again.

Parameters
Name Type Description
event Object Event object.
event.index Number Current index.
event.tabItem Object Tab item object.
swipe

Fires when the tabbar swipes.

Parameters
Name Type Description
event Object Event object.
event.index Number Current index.
event.options Object Animation options object.
update:activeIndex

Fired right after user interaction. Useful to update activeIndex prop.

Parameters
Name Type Description
event Number New value for index prop.

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.