Input · Checkbox

Checkbox

Checkboxes allow the user to select one or more items from a set.

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.

Semi Design
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>
Semi Design
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.

Semi Design
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统

Semi Design
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
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

Unchecked Disabled

Checked 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.

A
B
C
D
E
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.

Semi UI
Semi DSM
Semi D2C


Semi DSM
从 Semi Design,到 Any Design 快速定制你的设计系统,并应用在设计稿和代码中
Semi D2C
高效的 Design To Code 设计稿转代码


Photography
Movies
Running
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.

Checked Enabled

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.

Check all
Photography
Movies
Running
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.

单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
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.

单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
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.

A
B
C
D
E
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

PropertyDescriptionTypeDefault
modelValueWhether the checkbox is checked, controlled with v-model. Ignored inside a CheckboxGroup.booleanundefined
defaultCheckedWhether the checkbox is initially checked, for uncontrolled use. Ignored inside a CheckboxGroup.booleansemiDefault("Checkbox", "defaultChecked", false)
valueThe value this checkbox stands for in a CheckboxGroup. Without it the checkbox is not part of the group.CheckboxValueundefined
disabledWhether the checkbox is disabled.booleansemiGlobalDefault("Checkbox", "disabled")
indeterminateIndeterminate state. It only affects the appearance and the native input's indeterminate flag, never the checked value.booleansemiDefault("Checkbox", "indeterminate", false)
typeStyle type: default, card or pureCard. Inside a CheckboxGroup the group's type applies.CheckboxTypesemiDefault("Checkbox", "type", "default")
addonIdId of the addon node, which aria-labelledby points to. Generated when omitted.stringundefined
extraIdId of the extra node, which aria-describedby points to. Generated when omitted.stringundefined
prefixClsCSS class name prefix.stringsemiGlobalDefault("Checkbox", "prefixCls")
preventScrollWhether focusing prevents the browser from scrolling the element into view; applies to the focus method.booleansemiGlobalDefault("Checkbox", "preventScroll")

Events

EventDescriptionCallback parameters
update:modelValueEmitted when the checked state changes; drives v-model.[checked: boolean]
changeEmitted when the checked state changes. The event's target is { checked, value, name, disabled }.[event: CheckboxEvent]

Slots

SlotDescriptionScope parameters
defaultLabel content of the checkbox, which is also the native input's accessible name.any
extraSupplementary text, which aria-describedby points to.any

Exposes

NameDescriptionType
focusFocuses the native input.Type() => void
blurRemoves 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

PropertyDescriptionTypeDefault
modelValueSelected values, controlled with v-model.CheckboxValue[]undefined
defaultValueValues selected by default when uncontrolled, matched against each Checkbox's value.CheckboxValue[]semiDefault("CheckboxGroup", "defaultValue", [])
disabledWhether the whole group is disabled.booleansemiDefault("CheckboxGroup", "disabled", false)
nameThe name of every native input in the group. A unique value is generated per group when omitted.stringsemiGlobalDefault("CheckboxGroup", "name")
optionsDeclares the options as data. Each item is a string or { label, value, disabled, extra, class, style }.(string | CheckboxOptionItem)[]semiGlobalDefault("CheckboxGroup", "options")
directionLayout direction inside the group: horizontal or vertical.CheckboxDirectionsemiDefault("CheckboxGroup", "direction", "vertical")
typeStyle type of every Checkbox in the group: default, card or pureCard.CheckboxTypesemiDefault("CheckboxGroup", "type", "default")
prefixClsCSS class name prefix.stringsemiGlobalDefault("CheckboxGroup", "prefixCls")

Events

EventDescriptionCallback parameters
update:modelValueEmitted when the selected values change; drives v-model.[value: CheckboxValue[]]
changeEmitted when the selected values change, with the new array of values.[value: CheckboxValue[]]
blurEmitted when focus leaves the whole group; moving focus between its checkboxes does not emit it.[event: FocusEvent]

Slots

SlotDescriptionScope parameters
defaultCheckbox components in the group. Ignored when options is set.any
labelCustom label of each item in options, with the option and index scope parameters.CheckboxGroupOptionSlotProps
extraCustom extra text of each item in options, with the option and index scope parameters.CheckboxGroupOptionSlotProps

Exposes

NameDescriptionType
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 is group, 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 the aria-label prop 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-labelledby points to the addon node, used to explain the role of the current Checkbox; a passed aria-labelledby also lands on the input, placed before the addon id
  • aria-describedby points to the extra node, which is used to supplement the explanation of the current Checkbox
  • The checked and disabled states are expressed by the native input's checked and disabled; aria-checked and aria-disabled are 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

Call
IM
Ticket
Offline
Buzz
  • Capitalize the first letter
  • No punctuation

Design Tokens

These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.
Sass variableValueUsage
$transition_duration-checkbox-bgvar(--semi-transition_duration-none)复选框-背景色-动画持续时间
$transition_function-checkbox-bgvar(--semi-transition_function-easeIn)复选框-背景色-过渡曲线
$transition_delay-checkbox-bgvar(--semi-transition_delay-none)复选框-背景色-延迟时间
$transition_duration-checkbox-bordervar(--semi-transition_duration-none)复选框-边框-动画持续时间
$transition_function-checkbox-bordervar(--semi-transition_function-easeIn)复选框-边框-过渡曲线
$transition_delay-checkbox-bordervar(--semi-transition_delay-none)复选框-边框-延迟时间
$transform_scale-checkboxvar(--semi-transform_scale-none)复选框-放大
$spacing-checkbox_label-paddingLeft$spacing-tight文字与选框间距
$color-checkbox_label-text-defaultvar(--semi-color-text-0)文字颜色
$color-checkbox_default-bg-hovervar(--semi-color-fill-0)选框背景颜色 - 悬浮
$color-checkbox_default-bg-defaulttransparent复选框内部勾选框背景色 - 默认态
$color-checkbox_default-border-hovervar(--semi-color-focus-border)复选框内部勾选框描边颜色 - 悬停态
$color-checkbox_default-border-defaultvar(--semi-color-text-3)复选框内部勾选框描边颜色 - 默认态
$color-checkbox_default-bg-activevar(--semi-color-fill-1)选框未选中态背景颜色 - 按下
$font-checkbox_label-lineHeight20px文字行高
$color-checkbox_label-text-disabledvar(--semi-color-disabled-text)禁用文字颜色
$color-checkbox_checked-bg-defaultvar(--semi-color-primary)复选框选中态内部勾选框背景色 - 默认态
$color-checkbox_checked-bg-hovervar(--semi-color-primary-hover)选框选中态背景颜色 - 悬浮
$color-checkbox_checked-bg-activevar(--semi-color-primary-active)选框选中态背景颜色 - 按下
$color-checkbox_checked-icon-defaultvar(--semi-color-white)选框选中态对勾颜色 - 默认
$color-checkbox_checked-icon-hovervar(--semi-color-white)选框选中态对勾颜色 - 悬浮
$color-checkbox_checked-icon-activevar(--semi-color-white)选框选中态对勾颜色 - 按下
$color-checkbox_checked-border-defaultvar(--semi-color-primary)选框选中态描边颜色 - 默认
$color-checkbox_checked-border-hovervar(--semi-color-primary-hover)选框选中态描边颜色 - 悬浮
$color-checkbox_checked-border-activevar(--semi-color-primary-active)选框选中态描边颜色 - 按下
$color-checkbox_cardType_checked-bgvar(--semi-color-primary-light-default)卡片类型复选框选中时的背景颜色 - 默认
$color-checkbox_cardType_checked_disabled-bgvar(--semi-color-primary-light-default)卡片类型复选框选中且禁用时的背景颜色 - 默认
$color-checkbox_cardType-bg-hovervar(--semi-color-fill-0)卡片类型复选框选中时的背景颜色 - 悬浮
$color-checkbox_cardType-bg-activevar(--semi-color-fill-1)卡片类型复选框选中时的背景颜色 - 按下
$color-checkbox_cardType_checked_border-defaultvar(--semi-color-primary)卡片类型复选框选中时的边框颜色 - 默认
$color-checkbox_cardType_checked_border-hovervar(--semi-color-primary-hover)卡片类型复选框选中时的边框颜色 - 悬浮
$color-checkbox_cardType_checked_border-activevar(--semi-color-primary-active)卡片类型复选框选中时的边框颜色 - 按下
$color-checkbox_cardType_checked_disabled_border-defaultvar(--semi-color-primary-disabled)卡片类型复选框选中且禁用时的边框颜色 - 默认
$color-checkbox_cardType_addon-text-defaultvar(--semi-color-text-0)卡片类型复选框标题文本颜色 - 默认
$color-checkbox_cardType_extra-text-defaultvar(--semi-color-text-2)卡片复选框副标题文本颜色 - 默认
$color-checkbox_cardType_inner-bg-hovervar(--semi-color-white)卡片复选框内部勾选框背景色 - 悬浮
$color-checkbox_cardType_inner-bg-activevar(--semi-color-white)卡片复选框内部勾选框背景色 - 按下
$color-checkbox_cardType_inner-bg-defaultvar(--semi-color-white)卡片复选框内部勾选框背景色 -默认
$color-checkbox_disabled-bg-defaultvar(--semi-color-disabled-fill)选框禁用态背景颜色 - 默认
$color-checkbox_disabled-border-defaultvar(--semi-color-border)选框禁用态描边颜色 - 默认
$color-checkbox_checked-bg-disabledvar(--semi-color-primary-disabled)选框选中 + 禁用态背景颜色
$color-checkbox_checked-icon-disabledvar(--semi-color-white)选框禁用态对勾颜色
$color-checkbox_primary-outline-focus$color-focus-ring复选框轮廓-聚焦颜色
$color-checkbox_cardType-border-defaulttransparent卡片复选框默认边框颜色
$size-checkbox_inner-shadow$border-thickness-control选框内描边宽度
$width-checkbox_inner$width-icon-medium选框对勾 icon 宽度
$height-checkbox_inner20px选框对勾 icon 高度
$width-checkbox_cardType_checked-border1px卡片类型复选框的边框宽度
$width-checkbox_cardType_checked_disabled-border1px卡片类型复选框选中且禁用的边框宽度
$width-checkbox-outline$width-focus-ring复选框轮廓宽度
$radius-checkbox_cardType3px卡片类型复选框的圆角大小
$radius-checkbox_innervar(--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-defaultvar(--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-lineHeight20px卡片类型复选框的标题的文字行高
$font-checkbox_cardType_extra-size$font-size-regular卡片类型复选框的副标题的文字大小
$font-checkbox_cardType_extra-fontWeightnormal卡片类型复选框的副标题的 fontWeight
$font-checkbox_cardType_extra-lineHeight20px卡片类型复选框的副标题的文字行高