When to use
- When making multiple choices in a set of options;
- Use independently to select from different states, similar to the Switch component. The difference is that switching the Switch triggers a state change directly, while Checkbox is generally used for tagging status and works with the submission.
Demos
How to import
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
</script>
Basic Usage
When the Checkbox is used individually, you can control whether to check it through the defaultChecked and modelValue (v-model) props. When modelValue is passed in, it is controlled component.
Code
<script setup lang="ts">
import { Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-vue';
const onChange = (e: CheckboxEvent) => console.log(e);
</script>
<template>
<Checkbox aria-label="Checkbox 示例" @change="onChange">Semi Design</Checkbox>
</template>Code
<script setup lang="ts">
import { Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-vue';
const onChange = (e: CheckboxEvent) => console.log(e);
</script>
<template>
<Checkbox aria-label="Checkbox 示例" defaultChecked @change="onChange">Semi Design</Checkbox>
</template>You can use the #extra slot to add extra information. The extra information usually is longer and even has line changes.
Code
<script setup lang="ts">
import { Checkbox } from '@fibrous/semi-ui-vue';
const extra = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
</script>
<template>
<Checkbox aria-label="Checkbox 示例">
Semi Design
<template #extra>{{ extra }}</template>
</Checkbox>
<br />
<Checkbox aria-label="Checkbox 示例" :style="{ width: '280px' }">
Semi Design
<template #extra>{{ extra }}</template>
</Checkbox>
</template>Disabled
Code
<script setup lang="ts">
import { Checkbox } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Checkbox aria-label="Checkbox 示例" :defaultChecked="false" disabled>Unchecked Disabled</Checkbox>
<br />
<Checkbox aria-label="Checkbox 示例" defaultChecked disabled>Checked Disabled</Checkbox>
</div>
</template>Checkbox Group in JSX
By placing the Checkbox element inside the CheckboxGroup, you can declare the Checkbox group. Using the Checkbox group, you can more conveniently control the selection of a group of Checkboxes through the defaultValue and modelValue (v-model) props of the CheckboxGroup. At this time, Checkbox does not need to declare defaultChecked and modelValue.
Code
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
const values = ['A', 'B', 'C', 'D', 'E'];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['A', 'B']" :style="{ width: '100%' }">
<Checkbox v-for="value in values" :key="value" :value="value">{{ value }}</Checkbox>
</CheckboxGroup>
</template>Checkbox Group in options
You can pass an array using options to CheckboxGroup directly to generate a set of checkboxs.
Code
<script setup lang="ts">
import { CheckboxGroup, type CheckboxValue } from '@fibrous/semi-ui-vue';
const onChange = (checkedValues: CheckboxValue[]) => console.log('checked = ', checkedValues);
const plainOptions = ['Semi UI', 'Semi DSM', 'Semi D2C'];
const optionsWithExtra = [
{
extra: '从 Semi Design,到 Any Design 快速定制你的设计系统,并应用在设计稿和代码中',
label: 'Semi DSM',
value: 'dsm',
},
{ extra: '高效的 Design To Code 设计稿转代码', label: 'Semi D2C', value: 'd2c' },
];
const optionsWithDisabled = [
{ label: 'Photography', value: 'Photography' },
{ label: 'Movies', value: 'Movies' },
{ label: 'Running', value: 'Running', disabled: false },
];
</script>
<template>
<div>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['Semi D2C']" :options="plainOptions" @change="onChange" />
<br />
<br />
<CheckboxGroup aria-label="带 extra 示例" :defaultValue="[]" :options="optionsWithExtra" @change="onChange" />
<br />
<br />
<CheckboxGroup aria-label="Checkbox 示例" :defaultValue="['Photography']" disabled :options="optionsWithDisabled" @change="onChange" />
</div>
</template>Layout Direction
By setting direction to horizontal or vertical, You can adjust the layout within the Checkbox Group.
Code
<script setup lang="ts">
import { CheckboxGroup } from '@fibrous/semi-ui-vue';
const options = [
{ label: '抖音', value: 'abc' },
{ label: '今日头条', value: 'toutiao' },
];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" direction="horizontal" :options="options" />
</template>Controlled Component
Used as a controlled component.
Code
<script setup lang="ts">
import { computed, ref } from 'vue';
import { Button, Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-vue';
const checked = ref(true);
const disabled = ref(false);
const label = computed(() => `${checked.value ? 'Checked' : 'Unchecked'} ${disabled.value ? 'Disabled' : 'Enabled'}`);
const onChange = (e: CheckboxEvent) => console.log('checked = ', e.target.checked);
</script>
<template>
<div>
<div :style="{ marginBottom: '20px' }">
<Checkbox v-model="checked" aria-label="Checkbox 示例" :disabled="disabled" @change="onChange">
{{ label }}
</Checkbox>
</div>
<p>
<Button size="small" type="primary" @click="checked = !checked">{{ !checked ? 'Check' : 'Uncheck' }}</Button>
<Button size="small" :style="{ marginLeft: '10px' }" type="primary" @click="disabled = !disabled">
{{ !disabled ? 'Disable' : 'Enable' }}
</Button>
</p>
</div>
</template>Checkbox State
You may use the indeterminate property to set the state to indeterminate.
Code
<script setup lang="ts">
import { computed, ref } from 'vue';
import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrous/semi-ui-vue';
const plainOptions = ['Photography', 'Movies', 'Running'];
const checkedList = ref<CheckboxValue[]>(['Photography', 'Running']);
const checkAll = computed(() => checkedList.value.length === plainOptions.length);
const indeterminate = computed(() => checkedList.value.length > 0 && !checkAll.value);
const onCheckAllChange = (e: CheckboxEvent) => {
console.log(e);
checkedList.value = e.target.checked ? plainOptions : [];
};
</script>
<template>
<div>
<div :style="{ paddingBottom: '8px', borderBottom: '1px solid var(--semi-color-border)' }">
<Checkbox aria-label="Checkbox 示例" :indeterminate="indeterminate" :modelValue="checkAll" @change="onCheckAllChange"> Check all </Checkbox>
</div>
<CheckboxGroup v-model="checkedList" aria-label="CheckboxGroup 示例" :options="plainOptions" :style="{ marginTop: '6px' }" />
</div>
</template>Card Style
You can set type='card' to CheckboxGroup to realize card style with background.
Code
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
const extra = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
const items = [
{ value: '1', disabled: true },
{ value: '2', disabled: true },
{ value: '3', disabled: false },
{ value: '4', disabled: false },
];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['1', '3']" direction="vertical" type="card">
<Checkbox v-for="item in items" :key="item.value" :disabled="item.disabled" :style="{ width: '280px' }" :value="item.value">
单选框标题
<template #extra>{{ extra }}</template>
</Checkbox>
</CheckboxGroup>
</template>Pure Card Style
You can set type='pureCard' to CheckboxGroup to realize a pure card style with background and no checkbox.
Code
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
const extra = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
const items = [
{ value: '1', disabled: true },
{ value: '2', disabled: true },
{ value: '3', disabled: false },
{ value: '4', disabled: false },
];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['1', '3']" direction="vertical" type="pureCard">
<Checkbox v-for="item in items" :key="item.value" :disabled="item.disabled" :style="{ width: '280px' }" :value="item.value">
单选框标题
<template #extra>{{ extra }}</template>
</Checkbox>
</CheckboxGroup>
</template>Using with Grid
Use CheckboxGroup with Grid to achieve flexible layouts.
Code
<script setup lang="ts">
import { Checkbox, CheckboxGroup, Col, Row } from '@fibrous/semi-ui-vue';
const values = ['A', 'B', 'C', 'D', 'E'];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :style="{ width: '100%' }">
<Row>
<Col v-for="value in values" :key="value" :span="8">
<Checkbox :value="value">{{ value }}</Checkbox>
</Col>
</Row>
</CheckboxGroup>
</template>API Reference
Checkbox
Props
| Property | Description | Type | Default |
|---|---|---|---|
| modelValue | Whether the checkbox is checked, controlled with v-model. Ignored inside a CheckboxGroup. | boolean | undefined |
| defaultChecked | Whether the checkbox is initially checked, for uncontrolled use. Ignored inside a CheckboxGroup. | boolean | semiDefault("Checkbox", "defaultChecked", false) |
| value | The value this checkbox stands for in a CheckboxGroup. Without it the checkbox is not part of the group. | CheckboxValue | undefined |
| disabled | Whether the checkbox is disabled. | boolean | semiGlobalDefault("Checkbox", "disabled") |
| indeterminate | Indeterminate state. It only affects the appearance and the native input's indeterminate flag, never the checked value. | boolean | semiDefault("Checkbox", "indeterminate", false) |
| type | Style type: default, card or pureCard. Inside a CheckboxGroup the group's type applies. | CheckboxType | semiDefault("Checkbox", "type", "default") |
| addonId | Id of the addon node, which aria-labelledby points to. Generated when omitted. | string | undefined |
| extraId | Id of the extra node, which aria-describedby points to. Generated when omitted. | string | undefined |
| prefixCls | CSS class name prefix. | string | semiGlobalDefault("Checkbox", "prefixCls") |
| preventScroll | Whether focusing prevents the browser from scrolling the element into view; applies to the focus method. | boolean | semiGlobalDefault("Checkbox", "preventScroll") |
Events
| Event | Description | Callback parameters |
|---|---|---|
| update:modelValue | Emitted when the checked state changes; drives v-model. | [checked: boolean] |
| change | Emitted when the checked state changes. The event's target is { checked, value, name, disabled }. | [event: CheckboxEvent] |
Slots
| Slot | Description | Scope parameters |
|---|---|---|
| default | Label content of the checkbox, which is also the native input's accessible name. | any |
| extra | Supplementary text, which aria-describedby points to. | any |
Exposes
| Name | Description | Type |
|---|---|---|
| focus | Focuses the native input. | Type() => void |
| blur | Removes focus from the native input. | Type() => void |
class and style land on the root element. id, name, tabindex, autofocus, aria-* and focus and blur listeners passed as attrs land on the inner native input; other native attributes and listeners (such as @mouseenter) land on the root element. Inside a CheckboxGroup the group's name wins.
CheckboxGroup
Props
| Property | Description | Type | Default |
|---|---|---|---|
| modelValue | Selected values, controlled with v-model. | CheckboxValue[] | undefined |
| defaultValue | Values selected by default when uncontrolled, matched against each Checkbox's value. | CheckboxValue[] | semiDefault("CheckboxGroup", "defaultValue", []) |
| disabled | Whether the whole group is disabled. | boolean | semiDefault("CheckboxGroup", "disabled", false) |
| name | The name of every native input in the group. A unique value is generated per group when omitted. | string | semiGlobalDefault("CheckboxGroup", "name") |
| options | Declares the options as data. Each item is a string or { label, value, disabled, extra, class, style }. | (string | CheckboxOptionItem)[] | semiGlobalDefault("CheckboxGroup", "options") |
| direction | Layout direction inside the group: horizontal or vertical. | CheckboxDirection | semiDefault("CheckboxGroup", "direction", "vertical") |
| type | Style type of every Checkbox in the group: default, card or pureCard. | CheckboxType | semiDefault("CheckboxGroup", "type", "default") |
| prefixCls | CSS class name prefix. | string | semiGlobalDefault("CheckboxGroup", "prefixCls") |
Events
| Event | Description | Callback parameters |
|---|---|---|
| update:modelValue | Emitted when the selected values change; drives v-model. | [value: CheckboxValue[]] |
| change | Emitted when the selected values change, with the new array of values. | [value: CheckboxValue[]] |
| blur | Emitted when focus leaves the whole group; moving focus between its checkboxes does not emit it. | [event: FocusEvent] |
Slots
| Slot | Description | Scope parameters |
|---|---|---|
| default | Checkbox components in the group. Ignored when options is set. | any |
| label | Custom label of each item in options, with the option and index scope parameters. | CheckboxGroupOptionSlotProps |
| extra | Custom extra text of each item in options, with the option and index scope parameters. | CheckboxGroupOptionSlotProps |
Exposes
| Name | Description | Type |
|---|---|---|
| None |
Each item in options has the fields label, value, disabled, extra (string | number), class and style, and no onChange. Use the #label and #extra scoped slots for custom content. class, style and native attributes passed as attrs land on the root element. aria-invalid and aria-errormessage are passed to the native input of every Checkbox in the group; aria-required, tabindex and the aria-expanded, aria-haspopup, aria-controls injected by Tooltip are not rendered.
Methods
Checkbox
Call them through a template ref to the component instance; see Exposes above.
Accessibility
ARIA
- The role of Checkbox is
checkbox, the role of CheckboxGroup isgroup, and its children have no extra role aria-label: When using the Checkbox alone, if Children have no text, it is recommended to pass in thearia-labelprop to describe the function of the Checkbox in one sentence, which will make the screen reader read out the content of this label- The native input's
aria-labelledbypoints to theaddonnode, used to explain the role of the current Checkbox; a passedaria-labelledbyalso lands on the input, placed before theaddonid aria-describedbypoints to theextranode, which is used to supplement the explanation of the current Checkbox- The checked and disabled states are expressed by the native input's
checkedanddisabled;aria-checkedandaria-disabledare not rendered
Keyboard and focus
- Checkbox can be focused, keyboard users can use Tab and Shift + Tab to switch focus.
- The Checkbox that gets the focus can switch the selected and unselected states through Space.
- The click area of Checkbox is larger than the box itself and contains the text behind the box; for checkboxes with auxiliary text, the auxiliary text is also included in the click area.
- Disabled Checkbox is not focusable.
Content Guidelines
Checkbox Content Demo
- Capitalize the first letter
- No punctuation
Design Tokens
| Sass variable | Value | Usage |
|---|---|---|
| $transition_duration-checkbox-bg | var(--semi-transition_duration-none) | 复选框-背景色-动画持续时间 |
| $transition_function-checkbox-bg | var(--semi-transition_function-easeIn) | 复选框-背景色-过渡曲线 |
| $transition_delay-checkbox-bg | var(--semi-transition_delay-none) | 复选框-背景色-延迟时间 |
| $transition_duration-checkbox-border | var(--semi-transition_duration-none) | 复选框-边框-动画持续时间 |
| $transition_function-checkbox-border | var(--semi-transition_function-easeIn) | 复选框-边框-过渡曲线 |
| $transition_delay-checkbox-border | var(--semi-transition_delay-none) | 复选框-边框-延迟时间 |
| $transform_scale-checkbox | var(--semi-transform_scale-none) | 复选框-放大 |
| $spacing-checkbox_label-paddingLeft | $spacing-tight | 文字与选框间距 |
| $color-checkbox_label-text-default | var(--semi-color-text-0) | 文字颜色 |
| $color-checkbox_default-bg-hover | var(--semi-color-fill-0) | 选框背景颜色 - 悬浮 |
| $color-checkbox_default-bg-default | transparent | 复选框内部勾选框背景色 - 默认态 |
| $color-checkbox_default-border-hover | var(--semi-color-focus-border) | 复选框内部勾选框描边颜色 - 悬停态 |
| $color-checkbox_default-border-default | var(--semi-color-text-3) | 复选框内部勾选框描边颜色 - 默认态 |
| $color-checkbox_default-bg-active | var(--semi-color-fill-1) | 选框未选中态背景颜色 - 按下 |
| $font-checkbox_label-lineHeight | 20px | 文字行高 |
| $color-checkbox_label-text-disabled | var(--semi-color-disabled-text) | 禁用文字颜色 |
| $color-checkbox_checked-bg-default | var(--semi-color-primary) | 复选框选中态内部勾选框背景色 - 默认态 |
| $color-checkbox_checked-bg-hover | var(--semi-color-primary-hover) | 选框选中态背景颜色 - 悬浮 |
| $color-checkbox_checked-bg-active | var(--semi-color-primary-active) | 选框选中态背景颜色 - 按下 |
| $color-checkbox_checked-icon-default | var(--semi-color-white) | 选框选中态对勾颜色 - 默认 |
| $color-checkbox_checked-icon-hover | var(--semi-color-white) | 选框选中态对勾颜色 - 悬浮 |
| $color-checkbox_checked-icon-active | var(--semi-color-white) | 选框选中态对勾颜色 - 按下 |
| $color-checkbox_checked-border-default | var(--semi-color-primary) | 选框选中态描边颜色 - 默认 |
| $color-checkbox_checked-border-hover | var(--semi-color-primary-hover) | 选框选中态描边颜色 - 悬浮 |
| $color-checkbox_checked-border-active | var(--semi-color-primary-active) | 选框选中态描边颜色 - 按下 |
| $color-checkbox_cardType_checked-bg | var(--semi-color-primary-light-default) | 卡片类型复选框选中时的背景颜色 - 默认 |
| $color-checkbox_cardType_checked_disabled-bg | var(--semi-color-primary-light-default) | 卡片类型复选框选中且禁用时的背景颜色 - 默认 |
| $color-checkbox_cardType-bg-hover | var(--semi-color-fill-0) | 卡片类型复选框选中时的背景颜色 - 悬浮 |
| $color-checkbox_cardType-bg-active | var(--semi-color-fill-1) | 卡片类型复选框选中时的背景颜色 - 按下 |
| $color-checkbox_cardType_checked_border-default | var(--semi-color-primary) | 卡片类型复选框选中时的边框颜色 - 默认 |
| $color-checkbox_cardType_checked_border-hover | var(--semi-color-primary-hover) | 卡片类型复选框选中时的边框颜色 - 悬浮 |
| $color-checkbox_cardType_checked_border-active | var(--semi-color-primary-active) | 卡片类型复选框选中时的边框颜色 - 按下 |
| $color-checkbox_cardType_checked_disabled_border-default | var(--semi-color-primary-disabled) | 卡片类型复选框选中且禁用时的边框颜色 - 默认 |
| $color-checkbox_cardType_addon-text-default | var(--semi-color-text-0) | 卡片类型复选框标题文本颜色 - 默认 |
| $color-checkbox_cardType_extra-text-default | var(--semi-color-text-2) | 卡片复选框副标题文本颜色 - 默认 |
| $color-checkbox_cardType_inner-bg-hover | var(--semi-color-white) | 卡片复选框内部勾选框背景色 - 悬浮 |
| $color-checkbox_cardType_inner-bg-active | var(--semi-color-white) | 卡片复选框内部勾选框背景色 - 按下 |
| $color-checkbox_cardType_inner-bg-default | var(--semi-color-white) | 卡片复选框内部勾选框背景色 -默认 |
| $color-checkbox_disabled-bg-default | var(--semi-color-disabled-fill) | 选框禁用态背景颜色 - 默认 |
| $color-checkbox_disabled-border-default | var(--semi-color-border) | 选框禁用态描边颜色 - 默认 |
| $color-checkbox_checked-bg-disabled | var(--semi-color-primary-disabled) | 选框选中 + 禁用态背景颜色 |
| $color-checkbox_checked-icon-disabled | var(--semi-color-white) | 选框禁用态对勾颜色 |
| $color-checkbox_primary-outline-focus | $color-focus-ring | 复选框轮廓-聚焦颜色 |
| $color-checkbox_cardType-border-default | transparent | 卡片复选框默认边框颜色 |
| $size-checkbox_inner-shadow | $border-thickness-control | 选框内描边宽度 |
| $width-checkbox_inner | $width-icon-medium | 选框对勾 icon 宽度 |
| $height-checkbox_inner | 20px | 选框对勾 icon 高度 |
| $width-checkbox_cardType_checked-border | 1px | 卡片类型复选框的边框宽度 |
| $width-checkbox_cardType_checked_disabled-border | 1px | 卡片类型复选框选中且禁用的边框宽度 |
| $width-checkbox-outline | $width-focus-ring | 复选框轮廓宽度 |
| $radius-checkbox_cardType | 3px | 卡片类型复选框的圆角大小 |
| $radius-checkbox_inner | var(--semi-border-radius-extra-small) | 复选框内部勾选框圆角 |
| $spacing-checkbox_extra-marginTop | $spacing-extra-tight | 复选框副标题顶部内边距 |
| $spacing-checkbox_cardType-paddingX | $spacing-base | 卡片类型复选框的水平内间距 |
| $spacing-checkbox_cardType-paddingY | $spacing-base-tight | 卡片类型复选框的垂直内间距 |
| $spacing-checkbox_card_group_vertical-marginBottom | $spacing-base | 卡片样式复选框的下间距 |
| $color-checkbox_extra-text-default | var(--semi-color-text-2) | 复选框副标题文本颜色 |
| $spacing-checkbox_group_vertical-marginBottom | $spacing-base | |
| $spacing-checkbox_group_vertical_item-marginBottom | $spacing-base-tight | 垂直复选框组底部外边距 |
| $spacing-checkbox_group_horizontal-marginRight | $spacing-base | 水平复选框组右侧外边距 |
| $font-checkbox_cardType_addon-size | $font-size-regular | 卡片类型复选框标题文本大小 |
| $font-checkbox_cardType_addon-fontWeight | $font-weight-bold | 卡片类型复选框的标题的 fontWeight |
| $font-checkbox_cardType_addon-lineHeight | 20px | 卡片类型复选框的标题的文字行高 |
| $font-checkbox_cardType_extra-size | $font-size-regular | 卡片类型复选框的副标题的文字大小 |
| $font-checkbox_cardType_extra-fontWeight | normal | 卡片类型复选框的副标题的 fontWeight |
| $font-checkbox_cardType_extra-lineHeight | 20px | 卡片类型复选框的副标题的文字行高 |