Use FormControl to display an accessible checkbox form field. This Checkbox component is intended only as an ingredient for other custom components, or as a drop-in replacement for native HTML checkboxes outside of form use-cases.
If you do use this component to build a custom checkbox, it should always be accompanied by a corresponding <label> to improve support for assistive technologies.
The Checkbox component can be used in controlled and uncontrolled modes.
<form><FormControl><Checkbox id="default-checkbox" /><FormControl.Label>Default checkbox</FormControl.Label></FormControl><FormControl><Checkbox id="always-checked-checkbox" checked /><FormControl.Label>Always checked</FormControl.Label></FormControl><FormControl><Checkbox id="always-unchecked-checkbox" /><FormControl.Label>Always unchecked</FormControl.Label></FormControl><FormControl disabled><Checkbox id="inactive-checkbox" checked /><FormControl.Label>Inactive</FormControl.Label></FormControl></form>
An indeterminate checkbox state should be used if the input value is neither true nor false. This can be useful in situations where you are required to display an incomplete state, or one that is dependent on other input selections to determine a value.
<form><FormControl><Checkbox onChange={() => {}} indeterminate={true} /><FormControl.Label>Default checkbox</FormControl.Label></FormControl><FormControl><Checkbox checked={true} onChange={() => {}} /><FormControl.Label>Checkbox 1</FormControl.Label></FormControl><FormControl><Checkbox checked={false} onChange={() => {}} /><FormControl.Label>Checkbox 2</FormControl.Label></FormControl><FormControl><Checkbox checked={false} onChange={() => {}} /><FormControl.Label>Checkbox 3</FormControl.Label></FormControl><FormControl><Checkbox checked={false} onChange={() => {}} /><FormControl.Label>Checkbox 4</FormControl.Label></FormControl></form>
| Name | Type | Default | Description |
|---|---|---|---|
| checked | boolean | Modifies true/false value of the native checkbox | |
| defaultChecked | boolean | Checks the input by default in uncontrolled mode | |
| disabled | boolean | Modifies the native disabled state of the native checkbox | |
| indeterminate | boolean | false | Applies an indeterminate state to the checkbox |
| onChange | (event: React.ChangeEvent) => void | A callback function that is triggered when the checked state has been changed | |
| validationStatus | 'error' | 'success' | 'warning' | Only used to inform ARIA attributes. Individual checkboxes do not have validation styles. | |
| value | string | A unique value that is never shown to the user. Used during form submission and to identify which checkbox inputs are selected. | |
| sx | SystemStyleObject | Style overrides to apply to the component. See also overriding styles. | |
| ref | React.RefObject<HTMLInputElement> | A ref to the element rendered by this component. | |
Additional props are passed to the <input> element. See MDN for a list of props accepted by the <input> element. | |||