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 lang="ts">
    import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';
</script>

Basic Usage

When the Checkbox is used individually, a plain checked is only the initial checked state and the user's clicks toggle it afterwards. Use bind:checked to read and write the state; see "Controlled".

Semi Design
Code
<script lang="ts">
    import { Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';

    const onChange = (e: CheckboxEvent) => console.log(e);
</script>

<Checkbox aria-label="Checkbox 示例" {onChange}>Semi Design</Checkbox>
Semi Design
Code
<script lang="ts">
    import { Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';

    const onChange = (e: CheckboxEvent) => console.log(e);
</script>

<Checkbox aria-label="Checkbox 示例" checked {onChange}>Semi Design</Checkbox>

You can use extra to add extra information. It takes a snippet: define it inside the Checkbox tag with {#snippet extra()}...{/snippet}, and the rest of the content is the label. The extra information usually is longer and even has line changes.

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

Semi Design
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
Code
<script lang="ts">
    import { Checkbox } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
</script>

<Checkbox aria-label="Checkbox 示例">
    Semi Design
    {#snippet extra()}{extraText}{/snippet}
</Checkbox>
<br />
<Checkbox aria-label="Checkbox 示例" style="width: 280px">
    Semi Design
    {#snippet extra()}{extraText}{/snippet}
</Checkbox>

Disabled

Unchecked Disabled

Checked Disabled
Code
<script lang="ts">
    import { Checkbox } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Checkbox aria-label="Checkbox 示例" checked={false} disabled>Unchecked Disabled</Checkbox>
    <br />
    <Checkbox aria-label="Checkbox 示例" checked disabled>Checked Disabled</Checkbox>
</div>

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 value of the CheckboxGroup: a plain value is the initial value, and bind:value reads and writes it. At this time, Checkbox does not need to declare checked.

A
B
C
D
E
Code
<script lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const values = ['A', 'B', 'C', 'D', 'E'];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" style="width: 100%" value={['A', 'B']}>
    {#each values as value (value)}
        <Checkbox {value}>{value}</Checkbox>
    {/each}
</CheckboxGroup>

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 lang="ts">
    import { CheckboxGroup, type CheckboxValue } from '@fibrae/semi-ui-svelte';

    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>

<div>
    <CheckboxGroup aria-label="CheckboxGroup 示例" {onChange} options={plainOptions} value={['Semi D2C']} />
    <br />
    <br />
    <CheckboxGroup aria-label="带 extra 示例" {onChange} options={optionsWithExtra} value={[]} />
    <br />
    <br />
    <CheckboxGroup aria-label="Checkbox 示例" disabled {onChange} options={optionsWithDisabled} value={['Photography']} />
</div>

Layout Direction

By setting direction to horizontal or vertical, You can adjust the layout within the Checkbox Group.

抖音
今日头条
Code
<script lang="ts">
    import { CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const options = [
        { label: '抖音', value: 'abc' },
        { label: '今日头条', value: 'toutiao' },
    ];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" direction="horizontal" {options} />

Controlled Component

Used as a controlled component.

Checked Enabled

Code
<script lang="ts">
    import { Button, Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';

    let checked = $state(true);
    let disabled = $state(false);
    const label = $derived(`${checked ? 'Checked' : 'Unchecked'} ${disabled ? 'Disabled' : 'Enabled'}`);

    const onChange = (e: CheckboxEvent) => console.log('checked = ', e.target.checked);
</script>

<div>
    <div style="margin-bottom: 20px">
        <Checkbox aria-label="Checkbox 示例" bind:checked {disabled} {onChange}>
            {label}
        </Checkbox>
    </div>
    <p>
        <Button size="small" type="primary" onclick={() => (checked = !checked)}>{!checked ? 'Check' : 'Uncheck'}</Button>
        <Button size="small" style="margin-left: 10px" type="primary" onclick={() => (disabled = !disabled)}>
            {!disabled ? 'Disable' : 'Enable'}
        </Button>
    </p>
</div>

Checkbox State

You may use the indeterminate property to set the state to indeterminate.

Check all
Photography
Movies
Running
Code
<script lang="ts">
    import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrae/semi-ui-svelte';

    const plainOptions = ['Photography', 'Movies', 'Running'];
    let checkedList = $state<CheckboxValue[]>(['Photography', 'Running']);
    const checkAll = $derived(checkedList.length === plainOptions.length);
    const indeterminate = $derived(checkedList.length > 0 && !checkAll);

    const onCheckAllChange = (e: CheckboxEvent) => {
        console.log(e);
        checkedList = e.target.checked ? plainOptions : [];
    };
</script>

<div>
    <div style="padding-bottom: 8px; border-bottom: 1px solid var(--semi-color-border)">
        <Checkbox aria-label="Checkbox 示例" checked={checkAll} {indeterminate} onChange={onCheckAllChange}>Check all</Checkbox>
    </div>
    <CheckboxGroup aria-label="CheckboxGroup 示例" bind:value={checkedList} options={plainOptions} style="margin-top: 6px" />
</div>

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 lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
    const items = [
        { value: '1', disabled: true },
        { value: '2', disabled: true },
        { value: '3', disabled: false },
        { value: '4', disabled: false },
    ];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" direction="vertical" type="card" value={['1', '3']}>
    {#each items as item (item.value)}
        <Checkbox disabled={item.disabled} style="width: 280px" value={item.value}>
            单选框标题
            {#snippet extra()}{extraText}{/snippet}
        </Checkbox>
    {/each}
</CheckboxGroup>

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 lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
    const items = [
        { value: '1', disabled: true },
        { value: '2', disabled: true },
        { value: '3', disabled: false },
        { value: '4', disabled: false },
    ];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" direction="vertical" type="pureCard" value={['1', '3']}>
    {#each items as item (item.value)}
        <Checkbox disabled={item.disabled} style="width: 280px" value={item.value}>
            单选框标题
            {#snippet extra()}{extraText}{/snippet}
        </Checkbox>
    {/each}
</CheckboxGroup>

Using with Grid

Use CheckboxGroup with Grid to achieve flexible layouts.

A
B
C
D
E
Code
<script lang="ts">
    import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';

    const values = ['A', 'B', 'C', 'D', 'E'];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" style="width: 100%">
    <Row>
        {#each values as value (value)}
            <Col span={8}>
                <Checkbox {value}>{value}</Checkbox>
            </Col>
        {/each}
    </Row>
</CheckboxGroup>

API Reference

Checkbox

Props

PropertyDescriptionTypeDefault
addonIdId of the addon node, which aria-labelledby points to. Generated when omitted.string-
checkedWhether the checkbox is checked; bind it with bind:checked. Ignored inside a CheckboxGroup. bind:checked={get, set} makes it fully controlled; a plain checked is the initial value, a click overrides it inside the component, and a new value from the parent wins again.boolean-
childrenLabel content snippet of the checkbox, which is also the native input's accessible name. The rest of the tag's content is this snippet.Snippet-
disabledWhether the checkbox is disabled.booleanfalse
extraSnippet of the supplementary text, which aria-describedby points to.Snippet-
extraIdId of the extra node, which aria-describedby points to. Generated when omitted.string-
indeterminateIndeterminate state. It only affects the appearance and the native input's indeterminate flag, never the checked value.booleanfalse
nameThe native input's name. Inside a CheckboxGroup the group's name applies.string | null-
onChangeCalled when the checked state changes. The event's target is { checked, value, name, disabled }.Type(event: CheckboxEvent) => void-
onclickCalled when the root element is clicked, before the toggle.TypeMouseEventHandler<T> | null-
prefixClsCSS class name prefix.string-
preventScrollWhether focusing prevents the browser from scrolling the element into view; applies to the focus method.boolean-
typeStyle type: default, card or pureCard. Inside a CheckboxGroup the group's type applies.CheckboxType"default"
valueThe value this checkbox stands for in a CheckboxGroup. Without it the checkbox is not part of the group.CheckboxValue-

Methods

MethodDescriptionType
blurRemoves focus from the native input.Type() => void
focusFocuses the native input.Type() => void

class and style (a string) land on the root <span>. id, name, tabindex, autofocus, aria-*, onfocus and onblur land on the inner native input; other native attributes and events (such as onmouseenter) land on the root element, and onclick is called before the toggle. Inside a CheckboxGroup the group's name wins.

CheckboxGroup

Props

PropertyDescriptionTypeDefault
childrenCheckbox components in the group. Ignored when options is set.Snippet-
directionLayout direction inside the group: horizontal or vertical.CheckboxDirection"vertical"
disabledWhether the whole group is disabled.booleanfalse
extraSnippet for the extra text of each item in options, with the parameter { option, index }.TypeSnippet<[CheckboxGroupOptionSnippetProps]>-
labelSnippet for the label of each item in options, with the parameter { option, index }.TypeSnippet<[CheckboxGroupOptionSnippetProps]>-
nameThe name of every native input in the group. A unique value is generated per group when omitted.string-
onBlurCalled when focus leaves the whole group; moving focus between its checkboxes does not call it.Type(event: FocusEvent) => void-
onChangeCalled when the selected values change, with the new array of values.Type(value: CheckboxValue[]) => void-
onfocusoutCallback for the root element's focusout event, called before onBlur.TypeFocusEventHandler<T> | null-
optionsDeclares the options as data. Each item is a string or { label, value, disabled, extra, class, style }, where style is a string.TypeArray<string | CheckboxOptionItem>-
prefixClsCSS class name prefix.string-
typeStyle type of every Checkbox in the group: default, card or pureCard.CheckboxType"default"
valueSelected values, matched against each Checkbox's value; bind it with bind:value. bind:value={get, set} makes it fully controlled; a plain value is the initial value.CheckboxValue[]-

Each item in options has the fields label, value, disabled, extra (string | number), class and style (a string), and no onChange. Use the label and extra snippets, with the parameter { option, index }, for custom content. class, style (a string), native attributes and events land on the root <div>; onBlur is called when focus leaves the whole group, not when it moves between the checkboxes inside. 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 on the Checkbox instance obtained with bind:this; see Methods 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卡片类型复选框的副标题的文字行高