Checkboxes allow the user to select one or more items from a set.
API doc
Design doc
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 '@douyinfe/semi-ui';
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.
You can use extra to add extra information. The extra information usually is longer and even has line changes.
import React from 'react';
import { Checkbox } from '@douyinfe/semi-ui';
() => (
<>
<Checkbox
extra='Semi Design is a design system developed and maintained by IES Front-end Team and UED Team'
aria-label="Checkbox demo"
>
Semi Design
</Checkbox>
<br/>
<Checkbox
extra='Semi Design is a design system developed and maintained by IES Front-end Team and UED Team'
aria-label="Checkbox demo"
style={{ width: 400 }}
>
Semi Design
</Checkbox>
</>
);
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
You can pass an array using options to CheckboxGroup directly to generate a set of checkboxs.
import React from 'react';
import { CheckboxGroup } from '@douyinfe/semi-ui';
class App extends React.Component {
render() {
function onChange(checkedValues) {
console.log('checked = ', checkedValues);
}
const plainOptions = ['semi', 'vigo', 'helo'];
const options = [
{ label: 'Aim for the highest', value: '1', extra: "Raise the bar. Wait for bigger gains. Find the best solutions by widening your perspective. Be attentive. Distill ideas down to their fundamental truths. Keep learning and growing" },
{ label: 'Be grounded & courageous', value: '2', extra: "Make your own discoveries. Dive deep into facts. Stay level-headed. Focus on impact. Assume ownership, take risks, break the mold. Rapid iterations, multiple possibilities." },
{ label: 'Be open & humble', value: '3', extra: "Trust yourself, trust each other. Be willing to offer and ask for help. Collaboration creates value. Approach problems with the big picture in mind. Be mindful and check your ego; stay open to different ideas." },
{ label: 'Be candid & clear', value: '4', extra: "Dare to share your honest opinions. It's okay to make mistakes. Own it when you do. Stick to the facts, identify issues, and avoid \'leader-pleasing.\' Be accurate and forthright; be methodical and focused." }
];
const optionsWithDisabled = [
{ label: 'Photography', value: 'Photography' },
{ label: 'Movies', value: 'Movies' },
{ label: 'Running', value: 'Running', disabled: false },
];
return (
<div>
<CheckboxGroup options={plainOptions} defaultValue={['semi']} onChange={onChange} aria-label="CheckboxGroup demo" />
<br/><br/>
<CheckboxGroup options={options} defaultValue={[]} onChange={onChange} aria-label="CheckboxGroup demo" />
<br/><br/>
<CheckboxGroup
options={optionsWithDisabled}
disabled
defaultValue={['Photography']}
onChange={onChange}
aria-label="Checkbox demo"
/>
</div>
);
}
}
Layout Direction
By setting direction to horizontal or vertical, You can adjust the layout within the Checkbox Group.
id of addon node, aria-labelledby refers to this id, if not set, it will generate an id randomly provided after v2.11.0
string
aria-label
Define label of the Checkbox
string
-
checked
Specify whether the current Checkbox is selected (it is invalid when used in Group)
boolean
false
type
Set the type of checkboxe, one of: default、card、pureCard provided after v2.18.0
string
default
defaultChecked
Whether Checked by default (it is invalid when used in Group)
boolean
false
disabled
Disabled state
boolean
false
extra
Provide extra information >= v0.25.0
ReactNode
-
extraId
id of extra node. aria-describedby refers to this id, if not set, it will randomly generate an id provided after v2.11.0
ReactNode
-
value
The value that the checkbox represents in the CheckboxGroup
any
-
indeterminate
Set to indeterminate state, style control only
boolean
false
preventScroll
Indicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the user
boolean
onChange
Callback function when change
function(e: Event)
-
CheckboxGroup
PROPERTIES
Instructions
type
Default
defaultValue
Options selected by default
string\string[]
[]
direction
Layout of checkbox within a group, one of vertical, horizontal
string
vertical
disabled
Disable the entire group
boolean
false
name
The name attribute for all input[type="checkbox"] in Checkbox Group
string
-
options
Specify optional
any[]
[]
type
Set the type of checkboxes, one of: default、card、pureCard provided after v1.30.0
string
default
value
Specify selected options
any[]
[]
onChange
Callback function when selected options change
function(checkedValue)
-
Methods
Some internal methods provided by Checkbox can be accessed through ref:
Checkbox
Name
Description
blur()
Remove focus
focus()
Get focus
Accessibility
ARIA
The role of Checkbox is checkbox, the role of CheckboxGroup is list, and its direct child element is listitem
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. If you are using Form.Checkbox, you can use the label provided by Form without passing in aria-label
aria-labelledby points to the addon node, used to explain the role of the current Checkbox
aria-describedby points to the extra node, which is used to supplement the explanation of the current Checkbox
aria-disabled indicates the current disabled state, which is consistent with the value of the disabled prop
aria-checked indicates the current checked state
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.