TabBar

17:06

Description

A bottom navigation bar. Configure each item's icon, text, badge and raised button (midButton) via list, with v-model binding the active index by default. When an item sets pagePath, taps navigate with uni.switchTab, the active state is derived from the current page route (getCurrentPages) and v-model no longer participates; use beforeSwitch to intercept a switch.

Compatibility

Platform	Support
App	✅ Supported (gap has no effect; icon–text spacing is fixed)
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Select Demo Scene

The bottom tab bar is fixed at the bottom of the screen; switch scenes below to view different configurations.

Example 2

API

Props

Property	Description	Type	Default	Version
show	Whether to display	boolean	true	-
modelValue	v-model bound value	number	0	-
bgColor	Background color	string	''	-
height	Height	string	'50px'	-
iconSize	Icon size	string	DEFAULT_ICON_SIZE	-
midButtonSize	Center raised-button size	string	DEFAULT_MID_BUTTON_SIZE	-
activeColor	Active color	string	''	-
inactiveColor	Inactive color	string	''	-
midButton	Whether to show the center raised button	boolean	false	-
list	Tab list	TabbarItem[]	-	-
zIndex	z-index	string	''	-
beforeSwitch	Callback before switching	(index: number) => boolean | Promise<boolean>	-	-
borderTop	Whether to show the top border	boolean	true	-
hideTabBar	Whether to hide the native tab bar	boolean	true	-
gap	Spacing between icon and text	string	'2px'	-
textSize	Text size	string	DEFAULT_TEXT_SIZE	-
customClass	Custom class name	string	''	-
customStyle	Custom style	string	''	-

Events

Event	Description	Params	Version
change	Fires when a tab is tapped; the callback is the tapped tab index	index: number	-

Slots

ux-tabbar has no slots.

Notes

• hide-tab-bar defaults to true and calls uni.hideTabBar() on mount; on a non-tabBar page (such as the demo page) this throws hideTabBar:fail not TabBar page — pass hide-tab-bar="false" explicitly.
• When an item sets pagePath, taps navigate with uni.switchTab and the active state is derived from the current page route (getCurrentPages); v-model and change no longer drive that item. Only items without pagePath are tracked by v-model.
• beforeSwitch returning false (or a Promise resolving false) blocks the switch.
• The raised button requires both the global mid-button and that item's midButton: true.
• gap only takes effect on H5 / WeChat Mini Program; on App the icon–text spacing is fixed.