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 } from '@fibrous/semi-ui-react';

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-react';

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-react';

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-react';

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

Disabled

Unchecked Disabled

Checked Disabled

Code

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

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 { CheckboxGroup, Checkbox } from '@fibrous/semi-ui-react';

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-react';

export default function CheckboxDemo() {
    function 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 },
    ];
    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-react';

export default function CheckboxDemo() {
    const options = [
        { label: '抖音', value: 'abc' },
        { label: '今日头条', value: 'toutiao' },
    ];
    return <CheckboxGroup options={options} direction="horizontal" aria-label="CheckboxGroup 示例" />;
}

Controlled Component

Used as a controlled component.

Checked Enabled

Code

import { useState } from 'react';
import { Checkbox, Button, type CheckboxEvent } from '@fibrous/semi-ui-react';

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

    const toggleChecked = () => {
        setChecked(!checked);
    };

    const toggleDisable = () => {
        setDisabled(!disabled);
    };

    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={{ marginBottom: '20px' }}>
                <Checkbox checked={checked} disabled={disabled} onChange={onChange} aria-label="Checkbox 示例">
                    {label}
                </Checkbox>
            </div>
            <p>
                <Button type="primary" size="small" onClick={toggleChecked}>
                    {!checked ? 'Check' : 'Uncheck'}
                </Button>
                <Button style={{ marginLeft: '10px' }} type="primary" size="small" onClick={toggleDisable}>
                    {!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 { useState } from 'react';
import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrous/semi-ui-react';

export default function CheckboxDemo() {
    const plainOptions = ['Photography', 'Movies', 'Running'];
    const [checkedList, setCheckedList] = useState<CheckboxValue[]>(['Photography', 'Running']);
    const [indeterminate, setIndeterminate] = useState(true);
    const [checkAll, setCheckall] = useState(false);
    const onChange = (checkedList: CheckboxValue[]) => {
        setCheckedList(checkedList);
        setIndeterminate(!!checkedList.length && checkedList.length < plainOptions.length);
        setCheckall(checkedList.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={{ paddingBottom: 8, borderBottom: '1px solid var(--semi-color-border)' }}>
                <Checkbox indeterminate={indeterminate} onChange={onCheckAllChange} checked={checkAll} aria-label="Checkbox 示例">
                    Check all
                </Checkbox>
            </div>
            <CheckboxGroup style={{ marginTop: 6 }} 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 { CheckboxGroup, Checkbox } from '@fibrous/semi-ui-react';

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: 280 }}>
                单选框标题
            </Checkbox>
            <Checkbox value="2" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: 280 }}>
                单选框标题
            </Checkbox>
            <Checkbox value="3" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: 280 }}>
                单选框标题
            </Checkbox>
            <Checkbox value="4" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: 280 }}>
                单选框标题
            </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 { CheckboxGroup, Checkbox } from '@fibrous/semi-ui-react';

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: 280 }}>
                单选框标题
            </Checkbox>
            <Checkbox value="2" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: 280 }}>
                单选框标题
            </Checkbox>
            <Checkbox value="3" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: 280 }}>
                单选框标题
            </Checkbox>
            <Checkbox value="4" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: 280 }}>
                单选框标题
            </Checkbox>
        </CheckboxGroup>
    );
}

Using with Grid

Use CheckboxGroup with Grid to achieve flexible layouts.

Code

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

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`	-
autoFocus	Whether the native input receives focus on mount.	`boolean`	-
checked	Whether the checkbox is checked. Passing it makes the checkbox controlled. Ignored inside a CheckboxGroup that sets `value`.	`boolean`	-
children	Label of the checkbox, any `ReactNode`.	`React.ReactNode`	-
className	Class name of the root element.	`string`	-
defaultChecked	Whether the checkbox is initially checked, for uncontrolled use. Ignored inside a CheckboxGroup that sets `value`.	`boolean`	`false`
disabled	Whether the checkbox is disabled. Inside a CheckboxGroup that sets `value`, a disabled group disables it too.	`boolean`	-
extra	Supplementary text, any `ReactNode`, which `aria-describedby` points to.	`React.ReactNode`	-
extraId	Id of the extra node, which `aria-describedby` points to. Generated when omitted.	`string`	-
id	Id of the native input.	`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 that sets `value`, the group's `name` applies.	`string`	-
onChange	Called when the checked state changes. `e.target` holds the component's props plus `checked`, the new checked state.	`Type`	-
onMouseEnter	Called when the pointer enters the checkbox.	`Type`	-
onMouseLeave	Called when the pointer leaves the checkbox.	`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`	-
ref	Handle that provides the `focus()` and `blur()` methods.	`Type`	-
style	Style of the root `span` element.	`React.CSSProperties`	-
tabIndex	`tabIndex` of the native input, which receives focus.	`number`	-
type	Style type: `default`, `card` or `pureCard`. Inside a CheckboxGroup that sets `value`, 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.	`any`	-

Methods

Method	Description	Type
blur	Removes focus.	`Type`
focus	Moves focus to the checkbox, following `preventScroll`.	`Type`

className and style land on the root span. id, name, tabIndex, autoFocus, aria-label, aria-labelledby, aria-describedby, aria-errormessage, aria-invalid and aria-required land on the inner native input; other native attributes and events (such as role, onFocus, onBlur, onClick and data-*) land on the root span.

CheckboxGroup

Props

Property	Description	Type	Default
children	Checkboxes inside the group. Used when `options` is not set.	`React.ReactNode`	-
className	Class name of the root element.	`string`	-
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`
id	Id of the root element.	`string`	-
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, style, className, onChange }`; `label` and `extra` accept `ReactNode`.	`Type`	-
prefixCls	CSS class name prefix.	`string`	-
ref	Reference to the root element (`role="group"`).	`Type`	-
style	Style of the root element.	`React.CSSProperties`	-
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[]`	-

Other native attributes (such as aria-label and data-*) land on the root div (role="group"). onBlur fires only when focus leaves the whole group, not when it moves between Checkboxes in it. 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 and aria-controls injected by Tooltip are not rendered.

Methods

Some internal methods provided by Checkbox can be accessed through ref:

Checkbox

Call them through a ref to the Checkbox, see the API Reference 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

If you are using Form.Checkbox, you can use the label provided by Form without passing in aria-label; the label injected by Form also lands on the input's aria-labelledby, placed before the addon id

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