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
attributesCheckbox 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
PROPERTIES | Instructions | type | Default |
---|---|---|---|
addonId | 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 islist
, and its direct child element islistitem
aria-label
: When using the Checkbox alone, if Children have no text, it is recommended to pass in thearia-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 inaria-label
aria-labelledby
points to theaddon
node, used to explain the role of the current Checkboxaria-describedby
points to theextra
node, which is used to supplement the explanation of the current Checkboxaria-disabled
indicates the current disabled state, which is consistent with the value of thedisabled
proparia-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