Subsection

17:06

Description

Single choice from a set of options, in two shapes chosen by mode: button (default) shows a light track with a sliding button that moves between options, while subsection separates options with borders and fills the selected cell with active-color. current is the selected index (0-based); switching emits change(index).

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported (re-measures slider width and position on window resize)
WeChat Mini Program	✅ Supported

Examples

Button Mode

Default button mode; slider moves between buttons.

View source

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

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

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const current = ref<number>(0);

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

Subsection Mode

mode=subsection for segmented mode with borders between options.

View source

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

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

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const current = ref<number>(0);

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

Custom Colors

Customize active and inactive colors via active-color and inactive-color.

View source

<template>
    <ux-subsection :list="list" :current="current" active-color="#fa3534" inactive-color="#909399"></ux-subsection>
</template>

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

const list: SubsectionListItem[] = [
    { name: 'A' },
    { name: 'B' },
    { name: 'C' },
    { name: 'D' }
];

const current = ref<number>(1);
</script>

No Animation

animation=false disables slider animation.

View source

<template>
    <ux-subsection :list="list" :current="current" :animation="false" @change="onChange"></ux-subsection>
</template>

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

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const current = ref<number>(0);

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

Custom Style

Combine font-size, height, bg-color, button-color for custom appearance.

View source

<template>
    <ux-subsection :list="list" :current="current" :font-size="12" :height="30" bg-color="#ecf5ff" button-color="#2979ff" active-color="#ffffff" inactive-color="#2979ff"></ux-subsection>
</template>

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

const list: SubsectionListItem[] = [
    { name: 'Day' },
    { name: 'Week' },
    { name: 'Month' }
];

const current = ref<number>(0);
</script>

Disabled State

Set disabled=true to disable the whole component; a single item with disabled:true becomes unclickable.

View source

<template>
    <ux-subsection :list="list" disabled></ux-subsection>
    <view class="gap"></view>
    <ux-subsection :list="list2" active-color="#fa3534" inactive-color="#909399"></ux-subsection>
</template>

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

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const list2: SubsectionListItem[] = [
    { name: 'A' },
    { name: 'B', disabled: true },
    { name: 'C' }
];
</script>

<style scoped>
.gap {
    height: 10px;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
list	Option list; each item has a name text and an optional disabled	SubsectionListItem[]	-	-
current	Index of the selected option (0-based)	number | string	0	-
activeColor	Color of the selected option; defaults to $u.color.mainColor	string	''	-
inactiveColor	Color of unselected options; defaults to $u.color.contentColor	string	''	-
mode	Display mode: button – sliding button, subsection – segmented	SubsectionMode	'button'	-
fontSize	Option text size, in px	number | string	14	-
height	Component height, in px	number | string	35	-
animation	Whether to animate the sliding button	boolean	true	-
bold	Whether the selected option's text is bold	boolean	true	-
bgColor	Outer background color in button mode; defaults to $u.color.dividerColor	string	''	-
buttonColor	Sliding button color in button mode; defaults to $u.color.bgWhite	string	''	-
vibrateShort	Whether to trigger a light vibration on switch (skipped on the first switch)	boolean	false	-
disabled	Whether to disable the whole component	boolean	false	-

Events

Event	Description	Params	Version
change	Fires when the selected option changes; the callback is the selected index	index: number	-

Slots

ux-subsection has no slots.

Notes

1. current is controlled: update it from @change. A click first compares against the internal index, and returns early when the target is already selected, so change is not emitted again.
2. The slider width is measured from the first option (getBoundingClientRectAsync). H5 re-measures on window resize, while App / WeChat Mini Program only re-measure on mount and when list or mode changes; if the container width changes at runtime (e.g. orientation change), the slider may be misaligned.
3. bgColor / buttonColor apply to button mode only. In subsection mode the selected text is always white ($u.color.whiteColor), so a very light active-color makes it hard to read.
4. A disabled item, or a component with disabled, ignores clicks and emits no change. A disabled item's text drops to 0.4 opacity; the whole component drops to 0.6 when disabled.
5. With vibrateShort, the first switch does not vibrate (an internal first-touch guard); later switches do.