Select

17:06

Description

A bottom popup column selector built on picker-view. A boolean v-model controls popup open/close and list data is passed in externally. Supports single-column, mutil-column (independent columns) and mutil-column-auto (tree linkage via children); confirm returns the selected { value, label } of each column.

Compatibility

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

Examples

Single Column

mode=single-column, pass a 1D array via list.

View source

<template>
    <ux-button @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-select
        v-model="show"
        mode="single-column"
        :list="list"
        :default-value="[2]"
        title="单选选择器"
        @confirm="onConfirm"
    />
</template>

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

const show = ref<boolean>(false);
const result = ref<string>('');

const list: SelectListItem[] = [
    { label: '选项一', value: 1 },
    { label: '选项二', value: 2 },
    { label: '选项三', value: 3 },
    { label: '选项四', value: 4 }
];

function onConfirm(value: UTSJSONObject[]): void {
    if (value != null && value.length > 0) {
        result.value = value[0]['label'] as string;
    }
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

Multi Column

mode=mutil-column, pass a 2D array via list.

View source

<template>
    <ux-button @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-select
        v-model="show"
        mode="mutil-column"
        :list="list"
        :default-value="[0, 0]"
        title="多列选择器"
        @confirm="onConfirm"
    />
</template>

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

const show = ref<boolean>(false);
const result = ref<string>('');

const list: SelectListItem[][] = [
    [
        { label: '亚洲', value: 'asia' },
        { label: '欧洲', value: 'europe' }
    ],
    [
        { label: '中国', value: 'cn' },
        { label: '日本', value: 'jp' }
    ]
];

function joinLabels(value: UTSJSONObject[]): string {
    if (value == null) return '';
    const labels: string[] = [];
    for (let i = 0; i < value.length; i++) {
        const label = value[i]['label'] as string;
        if (label != null && label !== '') {
            labels.push(label);
        }
    }
    return labels.join(' / ');
}

function onConfirm(value: UTSJSONObject[]): void {
    result.value = joinLabels(value);
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

Cascade

mode=mutil-column-auto, use children for linkage.

View source

<template>
    <ux-button @click="show = true">打开选择器</ux-button>
    <text v-if="result !== ''" class="result">选择结果: {{ result }}</text>
    <ux-select
        v-model="show"
        mode="mutil-column-auto"
        :list="list"
        :default-value="[0, 0, 0]"
        title="级联选择器"
        @confirm="onConfirm"
    />
</template>

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

const show = ref<boolean>(false);
const result = ref<string>('');

const list: SelectListItem[] = [
    {
        label: '山东省',
        value: 'sd',
        children: [
            {
                label: '青岛市',
                value: 'qd',
                children: [
                    { label: '崂山区', value: 'ls' },
                    { label: '市南区', value: 'sn' }
                ]
            },
            {
                label: '济南市',
                value: 'jn',
                children: [
                    { label: '历下区', value: 'lx' },
                    { label: '市中区', value: 'sz' }
                ]
            }
        ]
    },
    {
        label: '海南省',
        value: 'hn',
        children: [
            {
                label: '三亚市',
                value: 'sy',
                children: [
                    { label: '海棠区', value: 'ht' },
                    { label: '吉阳区', value: 'jy' }
                ]
            }
        ]
    }
];

function joinLabels(value: UTSJSONObject[]): string {
    if (value == null) return '';
    const labels: string[] = [];
    for (let i = 0; i < value.length; i++) {
        const label = value[i]['label'] as string;
        if (label != null && label !== '') {
            labels.push(label);
        }
    }
    return labels.join(' / ');
}

function onConfirm(value: UTSJSONObject[]): void {
    result.value = joinLabels(value);
}
</script>

<style scoped>
.result {
    margin-top: 10px;
    font-size: 13px;
    color: #909399;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle		UTSJSONObject	-	-
customClass		string	''	-
list	Column data, passed in externally	SelectListItem[] | SelectListItem[][]	-	-
border	Whether to show the border	boolean	true	-
modelValue	v-model controls popup open/close	boolean	false	-
cancelColor	Cancel button color	string	''	-
confirmColor	Confirm button color	string	''	-
zIndex	Popup z-index	number | string	0	-
safeAreaInsetBottom	Whether to enable the bottom safe-area inset (default true; the internal ux-popup adds padding-bottom when mode=bottom)	boolean	true	-
maskCloseAble	Whether the popup can be closed by tapping the mask	boolean	true	-
defaultValue	Default selected index	number[]	-	-
preserveSelection	Whether to keep the user's last confirmed selection	boolean	true	-
mode	Mode: single-column, mutil-column, mutil-column-auto	SelectMode	'single-column'	-
valueName	Custom value field name	string	'value'	-
labelName	Custom label field name	string	'label'	-
childName	Custom children field name for the mutil-column-auto mode	string	'children'	-
title	Top title	string	''	-
cancelText	Cancel button text	string	''	-
confirmText	Confirm button text	string	''	-

Events

Event	Description	Params	Version
confirm		value: UTSJSONObject[]	-
cancel		-	-
click		-	-

Slots

ux-select has no slots.

Notes

1. Use a boolean v-model to control popup open/close; list data is passed in externally.
2. mode values: single-column (1D list), mutil-column (2D array), mutil-column-auto (tree, linked via children).
3. The confirm callback receives an array of selected items, each shaped like { value, label } (with extra when present); its length matches the column count.
4. default-value sets the default selected index of each column; when preserve-selection is true reopening reuses the last confirmed indices, otherwise default-value wins.
5. value-name / label-name / child-name customize the data field names (defaults value / label / children).
6. The border prop currently takes no part in rendering (the root node does not reference it); use custom-class for a custom border.
7. The bottom safe area is handled by the internal ux-popup (safe-area-inset-bottom); a z-index of 0 falls back to $u.zIndex.popup.