Checkbox

17:06

Description

Checkboxes are used for multiple selection. ux-checkbox-group groups the options, binds the selected name array via v-model, and centrally controls shape / size / active-color / max / disabled; ux-checkbox is a single option identified by name (or value), with label as the display text. ux-checkbox can also be used standalone, in which case its own model-value drives the checked state.

Compatibility

Platform	Support
App	✅ Supported (`ux-checkbox` root is block-level `flex`)
H5	✅ Supported (`ux-checkbox` root is `inline-flex`)
WeChat Mini Program	✅ Supported (`ux-checkbox` root is `inline-flex`)

Examples

Basic Usage

Bind the selected name array with v-model; max limits the maximum number of selections.

View source

vue

<template>
    <ux-checkbox-group v-model="values" :max="3">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <text class="result">已选: {{ values.join(',') }}</text>
</template>

<script setup lang="uts">
type FruitItem = {
    label: string;
    value: string;
    disabled: boolean;
};

const values = ref<string[]>(['荔枝']);

const list: FruitItem[] = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];
</script>

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

Batch Operations

Select all / deselect all by modifying the bound value.

View source

vue

<template>
    <ux-checkbox-group v-model="values">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <view class="btn-row">
        <ux-button size="small" shape="round" @click="setAll(false)">全不选</ux-button>
        <ux-button size="small" shape="round" type="primary" @click="setAll(true)">全选</ux-button>
    </view>
</template>

<script setup lang="uts">
type FruitItem = {
    label: string;
    value: string;
    disabled: boolean;
};

const values = ref<string[]>([]);

const list: FruitItem[] = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

function setAll(checked: boolean): void {
    values.value = checked ? list.map((item) => item.value) : [];
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    margin-top: 10px;
}
</style>

Shape

shape="square" is a square (3px small radius), shape="circle" is circular.

View source

vue

<template>
    <ux-checkbox-group v-model="values" :shape="shape">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <ux-subsection :list="shapeList" :current="shapeIndex" @change="setShape" />
</template>

<script setup lang="uts">
const values = ref<string[]>(['荔枝']);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const shape = ref<string>('square');

type ShapeOption = {
    name: string;
    value: string;
};

const shapeList: ShapeOption[] = [
    { name: 'square', value: 'square' },
    { name: 'circle', value: 'circle' }
];

const shapeIndex = computed((): number => shapeList.findIndex((item) => item.value === shape.value));

function setShape(index: number): void {
    shape.value = shapeList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

Size

Supports small / default / large presets and custom values (in px); with a numeric size, the icon and label scale to 0.6 and 0.8 of it.

View source

vue

<template>
    <ux-checkbox-group v-model="values" :size="size">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <ux-subsection :list="sizeList" :current="sizeIndex" @change="setSize" />
</template>

<script setup lang="uts">
const values = ref<string[]>(['荔枝']);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const size = ref<string>('default');

type SizeOption = {
    name: string;
    value: string;
};

const sizeList: SizeOption[] = [
    { name: 'small', value: 'small' },
    { name: 'default', value: 'default' },
    { name: 'large', value: 'large' },
    { name: '60', value: '60' }
];

const sizeIndex = computed((): number => sizeList.findIndex((item) => item.value === size.value));

function setSize(index: number): void {
    size.value = sizeList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

Active Color

Set the selected color via active-color, which overrides the group color.

View source

vue

<template>
    <ux-checkbox-group v-model="values" :active-color="activeColor">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <view class="btn-row">
        <ux-button v-for="(item, index) in colorList" :key="index" size="small" shape="round" :type="activeColor === item.value ? 'primary' : 'default'" @click="activeColor = item.value">{{ item.label }}</ux-button>
    </view>
</template>

<script setup lang="uts">
const values = ref<string[]>(['荔枝']);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const activeColor = ref<string>('');

type ColorOption = {
    name: string;
    value: string;
};

const colorList: ColorOption[] = [
    { name: 'primary', value: '' },
    { name: 'error', value: '#fa3534' },
    { name: 'warning', value: '#ff9900' },
    { name: 'success', value: '#19be6b' },
    { name: 'info', value: '#909399' }
];

const colorIndex = computed((): number => colorList.findIndex((item) => item.value === activeColor.value));

function setColor(index: number): void {
    activeColor.value = colorList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

Max Selections

Limit the maximum number of selections via max; a toast appears when exceeded.

View source

vue

<template>
    <ux-checkbox-group v-model="values" :max="max">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" />
    </ux-checkbox-group>
    <ux-subsection :list="maxList" :current="maxIndex" @change="setMax" />
</template>

<script setup lang="uts">
const values = ref<string[]>([]);

const list = [
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
];

const max = ref<number>(2);

type MaxOption = {
    name: string;
    value: number;
};

const maxList: MaxOption[] = [
    { name: '1', value: 1 },
    { name: '2', value: 2 },
    { name: '3', value: 3 }
];

const maxIndex = computed((): number => maxList.findIndex((item) => item.value === max.value));

function setMax(index: number): void {
    max.value = maxList[index].value;
}
</script>

<style scoped>
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 10px;
}
</style>

Disabled

Disable a single checkbox via disabled, or disable all via the group's disabled.

View source

vue

<template>
    <ux-checkbox-group v-model="values">
        <ux-checkbox v-for="(item, index) in list" :key="index" :label="item.label" :name="item.value" :disabled="item.disabled" />
    </ux-checkbox-group>
    <ux-button size="small" shape="round" :type="disabledFirst ? 'primary' : 'default'" @click="toggleDisabled">{{ disabledFirst ? '恢复第一个' : '禁用第一个' }}</ux-button>
</template>

<script setup lang="uts">
type FruitItem = {
    label: string;
    value: string;
    disabled: boolean;
};

const values = ref<string[]>(['荔枝']);

const list = ref<FruitItem[]>([
    { label: '荔枝', value: '荔枝', disabled: false },
    { label: '香蕉', value: '香蕉', disabled: false },
    { label: '橙子', value: '橙子', disabled: false },
    { label: '草莓', value: '草莓', disabled: false }
]);

const disabledFirst = ref<boolean>(false);

function toggleDisabled(): void {
    disabledFirst.value = !disabledFirst.value;
    list.value[0].disabled = disabledFirst.value;
}
</script>

API

Props

ux-checkbox-group

Property	Description	Type	Default	Version
`customStyle`	Custom root element style	`string \| UTSJSONObject`	`-`	-
`customClass`	Custom root element style class	`string`	`''`	-
`modelValue`	Bound value: an array of the selected checkbox `name`s	`(string \| number)[]`	`-`	-
`max`	Maximum number of checkboxes that can be selected	`number`	`999`	-
`disabled`	Whether to disable all checkboxes	`boolean`	`false`	-
`name`	Identifier used when submitting inside a form	`string \| boolean`	`''`	-
`labelDisabled`	Whether to disable tapping the label to select	`boolean`	`false`	-
`shape`	Shape	`'circle' \| 'square'`	`'square'`	-
`activeColor`	Color of the selected state	`string`	`''`	-
`size`	Overall component size	`string \| number`	`''`	-
`width`	Width of each checkbox	`string`	`'auto'`	-
`wrap`	Whether to wrap each checkbox onto its own line	`boolean`	`false`	-
`iconSize`	Icon size	`string \| number`	`''`	-

ux-checkbox

Property	Description	Type	Default	Version
`customStyle`	Custom root element style	`string \| UTSJSONObject`	`-`	-
`customClass`	Custom root element style class	`string`	`''`	-
`label`	Checkbox label	`string`	`''`	-
`name`	Checkbox identifier	`string \| number`	`''`	-
`value`	Checkbox value	`string \| number`	`''`	-
`shape`	Shape: square – square, circle – round	`'circle' \| 'square'`	`-`	-
`modelValue`	Whether it is checked (when used standalone)	`boolean`	`false`	-
`disabled`	Whether disabled	`boolean`	`-`	-
`labelDisabled`	Whether to disable tapping the label to select	`boolean`	`-`	-
`activeColor`	Color of the selected state; overrides the group's `active-color`	`string`	`-`	-
`iconSize`	Icon size, in px	`string \| number`	`-`	-
`labelSize`	Label font size	`string \| number`	`''`	-
`size`	Overall component size	`string \| number`	`-`	-

Events

ux-checkbox

Event	Description	Params	Version
`change`	Fires when this checkbox's state changes; the callback is a boolean	`value: boolean`	-

Slots

ux-checkbox-group

Slot	Description	Version
`default`	Place `ux-checkbox` children here	-

ux-checkbox

Slot	Description	Version
`default`	Custom label content (defaults to the label text)	-

Notes

ux-checkbox must be placed inside ux-checkbox-group to be grouped and participate in selection; standalone, its own model-value drives the checked state and change reports a boolean.
The selected value is kept by the group's v-model; ux-checkbox matches it by name (or value when set) — keep their types consistent with the bound value.
When the group's max is exceeded the option is not added and a "超过最大选择数量: N" toast is shown (max of 0 means unlimited).
ux-checkbox's disabled, label-disabled, size, icon-size, active-color override the same options on the group.
When ux-checkbox's size resolves to a size preset (including numeric), label-size is ignored and the font size comes from that preset (for numeric sizes the icon scales by 0.6 and the label by 0.8, each clamped).
When label-disabled is true, tapping the label does not toggle; only tapping the icon does.
On App the ux-checkbox root is block-level flex, while on H5 / WeChat Mini Program it is inline-flex, so standalone checkboxes placed in the same row may wrap differently.

Checkbox ​

Description ​

Compatibility ​

Examples ​

Basic Usage ​

Batch Operations ​

Shape ​

Size ​

Active Color ​

Max Selections ​

Disabled ​

API ​

Props ​

ux-checkbox-group ​

ux-checkbox ​

Events ​

ux-checkbox ​

Slots ​

ux-checkbox-group ​

ux-checkbox ​

Notes ​

Checkbox

Description

Compatibility

Examples

Basic Usage

Batch Operations

Shape

Size

Active Color

Max Selections

Disabled

API

Props

ux-checkbox-group

ux-checkbox

Events

ux-checkbox

Slots

ux-checkbox-group

ux-checkbox

Notes