Checkbox

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

import { Checkbox, CheckboxGroup, Col, Row } from '@fibrous/semi-ui-solid';

Basic Usage

When the Checkbox is used individually, you can control whether to check it through the defaultChecked and checked attributes. When checked is passed in, it is controlled component.

Semi Design

Code

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <Checkbox onChange={(e) => console.log(e)} aria-label="Checkbox 示例">
            Semi Design
        </Checkbox>
    );
}

Semi Design

Code

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <Checkbox defaultChecked onChange={(e) => console.log(e)} aria-label="Checkbox 示例">
            Semi Design
        </Checkbox>
    );
}

You can use extra 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

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <>
            <Checkbox aria-label="Checkbox 示例" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统">
                Semi Design
            </Checkbox>
            <br />
            <Checkbox style={{ width: '280px' }} aria-label="Checkbox 示例" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统">
                Semi Design
            </Checkbox>
        </>
    );
}

Disabled

Unchecked Disabled

Checked Disabled

Code

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <div>
            <Checkbox defaultChecked={false} disabled aria-label="Checkbox 示例">
                Unchecked Disabled
            </Checkbox>
            <br />
            <Checkbox defaultChecked disabled aria-label="Checkbox 示例">
                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 defaultValue and value properties of the CheckboxGroup. At this time, Checkbox does not need to declare defaultChecked and checked attributes.

Code

import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup style={{ width: '100%' }} defaultValue={['A', 'B']} aria-label="CheckboxGroup 示例">
            <Checkbox value="A">A</Checkbox>
            <Checkbox value="B">B</Checkbox>
            <Checkbox value="C">C</Checkbox>
            <Checkbox value="D">D</Checkbox>
            <Checkbox value="E">E</Checkbox>
        </CheckboxGroup>
    );
}

Checkbox Group in options

You can pass an array using options to CheckboxGroup directly to generate a set of checkboxs.

Code

import { CheckboxGroup, type CheckboxValue } from '@fibrous/semi-ui-solid';

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 },
];

function onChange(checkedValues: CheckboxValue[]) {
    console.log('checked = ', checkedValues);
}

export default function CheckboxDemo() {
    return (
        <div>
            <CheckboxGroup options={plainOptions} defaultValue={['Semi D2C']} onChange={onChange} aria-label="CheckboxGroup 示例" />
            <br />
            <br />
            <CheckboxGroup options={optionsWithExtra} defaultValue={[]} onChange={onChange} aria-label="带 extra 示例" />
            <br />
            <br />
            <CheckboxGroup options={optionsWithDisabled} disabled defaultValue={['Photography']} onChange={onChange} aria-label="Checkbox 示例" />
        </div>
    );
}

Layout Direction

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

抖音

今日头条

Code

import { CheckboxGroup } from '@fibrous/semi-ui-solid';

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

export default function CheckboxDemo() {
    return <CheckboxGroup options={options} direction="horizontal" aria-label="CheckboxGroup 示例" />;
}

Controlled Component

Used as a controlled component.

Checked Enabled

Code

import { createSignal } from 'solid-js';
import { Button, Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    const [checked, setChecked] = createSignal(true);
    const [disabled, setDisabled] = createSignal(false);

    const onChange = (e: CheckboxEvent) => {
        console.log('checked = ', e.target.checked);
        setChecked(e.target.checked);
    };

    const label = () => `${checked() ? 'Checked' : 'Unchecked'} ${disabled() ? 'Disabled' : 'Enabled'}`;
    return (
        <div>
            <div style={{ 'margin-bottom': '20px' }}>
                <Checkbox checked={checked()} disabled={disabled()} onChange={onChange} aria-label="Checkbox 示例">
                    {label()}
                </Checkbox>
            </div>
            <p>
                <Button type="primary" size="small" onClick={() => setChecked(!checked())}>
                    {!checked() ? 'Check' : 'Uncheck'}
                </Button>
                <Button style={{ 'margin-left': '10px' }} type="primary" size="small" onClick={() => setDisabled(!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

import { createSignal } from 'solid-js';
import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrous/semi-ui-solid';

const plainOptions = ['Photography', 'Movies', 'Running'];

export default function CheckboxDemo() {
    const [checkedList, setCheckedList] = createSignal<CheckboxValue[]>(['Photography', 'Running']);
    const [indeterminate, setIndeterminate] = createSignal(true);
    const [checkAll, setCheckAll] = createSignal(false);
    const onChange = (list: CheckboxValue[]) => {
        setCheckedList(list);
        setIndeterminate(!!list.length && list.length < plainOptions.length);
        setCheckAll(list.length === plainOptions.length);
    };
    const onCheckAllChange = (e: CheckboxEvent) => {
        console.log(e);
        setCheckedList(e.target.checked ? plainOptions : []);
        setIndeterminate(false);
        setCheckAll(e.target.checked);
    };

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

import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup type="card" defaultValue={['1', '3']} direction="vertical" aria-label="CheckboxGroup 示例">
            <Checkbox value="1" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="2" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="3" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="4" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
        </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

import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup type="pureCard" defaultValue={['1', '3']} direction="vertical" aria-label="CheckboxGroup 示例">
            <Checkbox value="1" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="2" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="3" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="4" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
        </CheckboxGroup>
    );
}

Using with Grid

Use CheckboxGroup with Grid to achieve flexible layouts.

Code

import { Checkbox, CheckboxGroup, Col, Row } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup style={{ width: '100%' }} aria-label="CheckboxGroup 示例">
            <Row>
                <Col span={8}>
                    <Checkbox value="A">A</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="B">B</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="C">C</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="D">D</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="E">E</Checkbox>
                </Col>
            </Row>
        </CheckboxGroup>
    );
}

API Reference

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. Passing it makes the checkbox controlled. Ignored inside a CheckboxGroup.	`boolean`	-
defaultChecked	Whether the checkbox is initially checked, for uncontrolled use. Ignored inside a CheckboxGroup.	`boolean`	`false`
disabled	Whether the checkbox is disabled.	`boolean`	-
extra	Supplementary text, any JSX, which aria-describedby points to.	`JSX.Element`	-
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 name of the native input. Inside a CheckboxGroup the group's name applies.	`string`	-
onBlur	Called when the native input loses focus.	`Type`	-
onChange	Called when the checked state changes. The event's `target` is `{ checked, value, name, disabled }`.	`Type`	-
onFocus	Called when the native input gains focus.	`Type`	-
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`	-

class, style and ref 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 and onClick) land on the root element. Inside a CheckboxGroup the group's name wins.

CheckboxGroup

Props

Property	Description	Type	Default
defaultValue	Values selected by default when uncontrolled, matched against each Checkbox's value.	`CheckboxValue[]`	`[]`
direction	Layout direction inside the group: horizontal or vertical.	`CheckboxDirection`	`"vertical"`
disabled	Whether the whole group is disabled.	`boolean`	`false`
name	The name of every native input in the group. A unique value is generated per group when omitted.	`string`	-
onChange	Called when the selected values change, with the new array of values.	`Type`	-
options	Declares the options as data. Each item is a string or `{ label, value, disabled, extra, class, style, onChange }`; label and extra accept JSX.	`Type`	-
prefixCls	CSS class name prefix.	`string`	-
type	Style type of every Checkbox in the group: default, card or pureCard.	`CheckboxType`	`"default"`
value	Selected values. Passing it makes the group controlled.	`CheckboxValue[]`	-

class, style, ref and 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

ref receives the root <span>, and its focus() and blur() act on the inner native input. focus() passes preventScroll along.

Name	Description
blur()	Remove focus
focus()	Get focus

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

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 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	卡片类型复选框的副标题的文字行高