A component to display a tab bar on the bottom of a page. Used with <ons-tab> to manage pages using tabs.
In Onsen UI tab navigation is enabled using the <ons-tabbar> element.
Tabs are added using <ons-tab> which is a child of <ons-tabbar>:
<ons-tabbar>
<ons-tab label="Tab 1" active></ons-tab>
<ons-tab label="Tab 2"></ons-tab>
</ons-tabbar>
The active attribute is used to define the tab which should be open by default. If this attribute is not provided, the first page will be activated by default.
<ons-tab> elementA tab accepts multiple attriutes to change its style and behavior, i.e. page, label or icon.
Alternatively, the content can be directly provided as ons-tab children:
<ons-tab page="...">
<input type="radio" style="display: none">
<button class="tabbar__button">
<div class="tabbar__icon">
<ons-icon icon="my-icon"></ons-icon>
</div>
<div class="tabbar__label">My Label</div>
<div class="tabbar__badge notification">99</div>
</button>
</ons-tab>
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. Optionally, max-width CSS property can be specified to set the width of the tab (for each tab).
Binding pages to the tabs works very similar to the <ons-navigator>.
The content of the pages is defined using the <template> element:
<template id="tab1.html">
<ons-page>
...
</ons-page>
</template>
and in order to bind a template to a specific tab the page attribute is used on the <ons-tab> element:
<ons-tab
label="Tab 1"
page="tab1.html">
</ons-tab>
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:
<ons-tabbar swipeable animation="none">...</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).
| Name | Type | Description |
|---|---|---|
| animation |
String
none |
If this attribute is set to "none" the transitions will not be animated.
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.
|
| position |
String
bottom |
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.
Works only during initialization.
|
| swipeable | If this attribute is set the tab bar can be scrolled by drag or swipe. Optional. | |
| ignore-edge-width |
Number
20 |
Distance in pixels from both edges. Swiping on these areas will prioritize parent components such as ons-splitter or ons-navigator.
Optional.
|
| active-index |
Number
0 |
The index of the tab that is currently active. Optional. |
| hide-tabs | Whether to hide the tabs. Optional. | |
| tab-border | 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. | |
| modifier | String | The appearance of the tabbar. Optional. |
| var | String | Variable name to refer this tab bar. Optional. Works only during initialization. |
| ons-reactive | Expression | Allows you to specify custom behavior when the “reactive” event is fired. Optional. Works only during initialization. |
| ons-prechange | Expression | Allows you to specify custom behavior when the “prechange” event is fired. Optional. Works only during initialization. |
| ons-postchange | Expression | Allows you to specify custom behavior when the “postchange” 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'}.
|
| activeIndex | The index of the tab that is currently active. |
| hideTabs | Whether to hide the tabs. |
| tabBorder | If this property is set the tabs show a dynamic bottom border. Only works for iOS flat design since the border is always visible in Material Design. |
| visible | Whether the tabbar is visible or not. |
| swipeable | Enable swipe interaction. |
| onSwipe | Hook called whenever the user slides the tabbar. It gets a decimal index and an animationOptions object as arguments. |
| 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. |
| Signature | Description |
|---|---|
| setActiveTab(index, [options]) | Show specified tab page. Animations and their options can be specified by the second parameter. |
| setTabbarVisibility(visible) | Used to hide or show the tab bar. |
| getActiveTabIndex() | Returns tab index on current active tab. If active tab is not found, returns -1. |
| 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. |
Show specified tab page. Animations and their options can be specified by the second parameter.
Returns: A promise that resolves to the new page element.
| Name | Type | Description |
|---|---|---|
| index | Number | Tab index. |
| options | Object | Parameter object. |
| options.callback | Function | Function that runs when the new page has loaded. |
| options.animation | String | If this option is “none”, the transition won’t slide. |
| options.animationOptions | String |
Specify the animation’s duration, delay and timing. E.g. {duration: 0.2, delay: 0.4, timing: 'ease-in'}.
|
Used to hide or show the tab bar.
| Name | Type | Description |
|---|---|---|
| visible | Boolean |
Returns tab index on current active tab. If active tab is not found, returns -1.
Returns: The index of the currently active tab.
Add an event listener.
| Name | Type | Description |
|---|---|---|
| eventName | String | Name of the event. |
| listener | Function | Function to execute when the event is triggered. |
Add an event listener that’s only triggered once.
| Name | Type | Description |
|---|---|---|
| eventName | String | Name of the event. |
| listener | Function | Function to execute when the event is triggered. |
Remove an event listener. If the listener is not specified all listeners for the event type will be removed.
| 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 |
|---|---|
| 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. |
Fires just before the tab is changed.
| 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. |
Fires just after the tab is changed.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.index | Number | Current index. |
| event.tabItem | Object | Tab item object. |
Fires if the already open tab is tapped again.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.index | Number | Current index. |
| event.tabItem | Object | Tab item object. |
Fires when the tabbar swipes.
| Name | Type | Description |
|---|---|---|
| event | Object | Event object. |
| event.index | Number | Current index. |
| event.options | Object | Animation options object. |
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.