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".
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>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.
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
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.
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.
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.
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.
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.
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.
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.
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
| Property | Description | Type | Default |
|---|---|---|---|
| addonId | Id of the addon node, which aria-labelledby points to. Generated when omitted. | string | - |
| checked | Whether 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 | - |
| children | Label 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 | - |
| disabled | Whether the checkbox is disabled. | boolean | false |
| extra | Snippet of the supplementary text, which aria-describedby points to. | Snippet | - |
| extraId | Id of the extra node, which aria-describedby points to. Generated when omitted. | string | - |
| indeterminate | Indeterminate state. It only affects the appearance and the native input's indeterminate flag, never the checked value. | boolean | false |
| name | The native input's name. Inside a CheckboxGroup the group's name applies. | string | null | - |
| onChange | Called when the checked state changes. The event's target is { checked, value, name, disabled }. | Type(event: CheckboxEvent) => void | - |
| onclick | Called when the root element is clicked, before the toggle. | TypeMouseEventHandler<T> | null | - |
| prefixCls | CSS class name prefix. | string | - |
| preventScroll | Whether focusing prevents the browser from scrolling the element into view; applies to the focus method. | boolean | - |
| type | Style type: default, card or pureCard. Inside a CheckboxGroup the group's type applies. | CheckboxType | "default" |
| value | The value this checkbox stands for in a CheckboxGroup. Without it the checkbox is not part of the group. | CheckboxValue | - |
Methods
| Method | Description | Type |
|---|---|---|
| blur | Removes focus from the native input. | Type() => void |
| focus | Focuses 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
| Property | Description | Type | Default |
|---|---|---|---|
| children | Checkbox components in the group. Ignored when options is set. | Snippet | - |
| direction | Layout direction inside the group: horizontal or vertical. | CheckboxDirection | "vertical" |
| disabled | Whether the whole group is disabled. | boolean | false |
| extra | Snippet for the extra text of each item in options, with the parameter { option, index }. | TypeSnippet<[CheckboxGroupOptionSnippetProps]> | - |
| label | Snippet for the label of each item in options, with the parameter { option, index }. | TypeSnippet<[CheckboxGroupOptionSnippetProps]> | - |
| name | The name of every native input in the group. A unique value is generated per group when omitted. | string | - |
| onBlur | Called when focus leaves the whole group; moving focus between its checkboxes does not call it. | Type(event: FocusEvent) => void | - |
| onChange | Called when the selected values change, with the new array of values. | Type(value: CheckboxValue[]) => void | - |
| onfocusout | Callback for the root element's focusout event, called before onBlur. | TypeFocusEventHandler<T> | null | - |
| options | Declares the options as data. Each item is a string or { label, value, disabled, extra, class, style }, where style is a string. | TypeArray<string | CheckboxOptionItem> | - |
| prefixCls | CSS class name prefix. | string | - |
| type | Style type of every Checkbox in the group: default, card or pureCard. | CheckboxType | "default" |
| value | Selected 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 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 | 卡片类型复选框的副标题的文字行高 |