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

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.

Disabled

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

Checkbox Group in options

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

Layout Direction

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

Controlled Component

Used as a controlled component.

Checkbox State

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

Card Style

version: >=1.30.0
You can set type='card' to CheckboxGroup to realize card style with background.

Pure Card Style

version: >=1.30.0
You can set type='pureCard' to CheckboxGroup to realize a pure card style with background and no checkbox.

Using with Grid

Use Checkbox.Group with Grid to achieve flexible layouts.

API Reference

Checkbox

PROPERTIESInstructionstypeDefault
addonIdid 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-labelDefine label of the Checkboxstring-
checkedSpecify whether the current Checkbox is selected (it is invalid when used in Group)booleanfalse
typeSet the type of checkboxe, one of: default、card、pureCard
provided after v2.18.0		stringdefault
defaultCheckedWhether Checked by default (it is invalid when used in Group)booleanfalse
disabledDisabled statebooleanfalse
extraProvide extra information
>= v0.25.0		ReactNode-
extraIdid of extra node. aria-describedby refers to this id, if not set, it will randomly generate an id
provided after v2.11.0		ReactNode-
valueThe value that the checkbox represents in the CheckboxGroupany-
indeterminateSet to indeterminate state, style control onlybooleanfalse
preventScrollIndicates 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 userboolean
onChangeCallback function when changefunction(e: Event)-

CheckboxGroup

PROPERTIESInstructionstypeDefault
defaultValueOptions selected by defaultstring\string[][]
directionLayout of checkbox within a group, one of vertical, horizontalstringvertical
disabledDisable the entire groupbooleanfalse
nameThe name attribute for all input[type="checkbox"] in Checkbox Groupstring-
optionsSpecify optionalany[][]
typeSet the type of checkboxes, one of: default、card、pureCard
provided after v1.30.0		stringdefault
valueSpecify selected optionsany[][]
onChangeCallback function when selected options changefunction(checkedValue)-

Methods

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

Checkbox

NameDescription
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.
  • Disabled Checkbox is not focusable.

Content Guidelines

Checkbox Content Demo
Call
IM
Ticket
Offline
Buzz
  • Capitalize the first letter
  • No punctuation

Design Tokens