Tabs

17:06

Description

A tab bar. Render tabs from list, with a built-in bottom indicator and badges. With is-scroll (default true) the tabs scroll horizontally and the active tab auto-scrolls to the center of the viewport; set it to false to distribute tabs evenly with no sliding. Tapping a tab emits change; update current externally to control the active tab.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Scrollable by default, the active tab auto-centers and triggers a change event on click.

View source

<template>
    <ux-tabs :list="list" :current="current" @change="onChange" />
</template>

<script setup lang="uts">
import type { TabsItem } from '@/uni_modules/uview-pro-x';

const current = ref<number>(0);

const list: TabsItem[] = [
    { name: '标签一' },
    { name: '标签二' },
    { name: '标签三' },
    { name: '标签四' },
    { name: '标签五' }
];

const onChange = (index: number) => {
    current.value = index;
};
</script>

Disable Scroll

When is-scroll=false tabs are evenly distributed and cannot slide.

View source

<template>
    <ux-tabs :list="list" :is-scroll="false" :current="current" @change="onChange" />
</template>

<script setup lang="uts">
import type { TabsItem } from '@/uni_modules/uview-pro-x';

const current = ref<number>(0);

const list: TabsItem[] = [
    { name: '标签一' },
    { name: '标签二' },
    { name: '标签三' }
];

const onChange = (index: number) => {
    current.value = index;
};
</script>

Custom Colors

Customize active/inactive text colors via active-color / inactive-color.

View source

<template>
    <ux-tabs :list="list" active-color="#ffa500" inactive-color="#909399" :current="current" @change="onChange" />
</template>

<script setup lang="uts">
import type { TabsItem } from '@/uni_modules/uview-pro-x';

const current = ref<number>(0);

const list: TabsItem[] = [
    { name: '标签一' },
    { name: '标签二' },
    { name: '标签三' }
];

const onChange = (index: number) => {
    current.value = index;
};
</script>

Badge

The count field in list data displays a badge; is-dot switches to a dot.

View source

<template>
    <ux-tabs :list="list" :is-scroll="false" :current="current" @change="onChange" />
</template>

<script setup lang="uts">
import type { TabsItem } from '@/uni_modules/uview-pro-x';

const current = ref<number>(0);

const list: TabsItem[] = [
    { name: '标签一', count: 5 },
    { name: '标签二', count: 20 },
    { name: '标签三', count: 100 },
    { name: '标签四' }
];

const onChange = (index: number) => {
    current.value = index;
};
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
isScroll	Whether tabs can be dragged horizontally	boolean	true	-
list	Tab array	TabsItem[]	-	-
current	Index of the current active tab	string | number	0	-
height	Navbar height and line height	string | number	40	-
fontSize	Font size, in px	string | number	15	-
duration	Transition duration, in seconds	string | number	0.5	-
activeColor	Theme color of the selected item	string	''	-
inactiveColor	Color of unselected items	string	''	-
barWidth	Width of the bottom moving bar, in px	string | number	20	-
barHeight	Height of the moving bar, in px	string | number	3	-
gutter	Total left/right padding of a single tab, in px	string | number	20	-
bgColor	Background color of the navbar	string	''	-
name	Property read from each array object for the tab name	string	'name'	-
count	Property read from each array object for the badge count	string	'count'	-
offset	Badge position offset	number[]	-	-
isDot	Whether the badge is a dot	boolean	false	-
bold	Whether the active tab font is bold	boolean	true	-
activeItemStyle	Style of the current active tab item	UTSJSONObject	-	-
showBar	Whether to show the bottom indicator	boolean	true	-
barStyle	Custom style of the bottom indicator	UTSJSONObject	-	-
itemWidth	Tab width	string | number	'auto'	-

Events

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

Slots

ux-tabs has no slots.

Notes

• Tapping the already-active tab does not fire change again (the source returns early when the index is unchanged).
• current is maintained externally (the component does not increment it internally); update it in the change callback.
• When the length of list changes, the component resets the current index to 0.
• The badge is driven by each list item's count; it is hidden when count is 0 or unset, and is-dot renders it as a dot.
• In scroll mode (is-scroll=true) gutter becomes the tab's left/right padding; in non-scroll mode tabs are evenly distributed and item-width stays auto.
• duration is in seconds; the indicator does not animate on its first appearance.