Checkbox is a form component that shows a checkbox with it's label.
Checkbox.Group is a component that makes it easier to handle group of checkboxes.
How to use Checkbox
You can use the Checkbox as a controlled or uncontrolled input.
Using as a controlled input
For using the Checkbox as a controlled input, you need to:
- Pass the
isCheckedproperty, with this property it will already be a controlled component; - Pass a
onChangehandler, so you can use it to update the value ofisChecked;
Setting the isChecked will already define it as a controlled input.
const ExampleControlled = () => {const [checkboxState, setCheckboxState] = useState(false);return (<Checkboxname="newsletter-subscribe-controlled"id="newsletter-subscribe-controlled"isChecked={checkboxState}onChange={() => setCheckboxState(!checkboxState)}>Subscribe to newsletter</Checkbox>);};
Using as an uncontrolled input
You can use the Checkbox as an uncontrolled input, for that you can:
- Set the
defaultCheckedproperty, it will ensure that the checked state can be altered normally. - Don't set the
isCheckedas it will make the input controlled.
<Checkboxname="newsletter-subscribe-uncontrolled"id="newsletter-subscribe-uncontrolled"defaultChecked>Subscribe to newsletter</Checkbox>
Using with Group
We also provide the Checkbox.Group component that helps when using multiple checkboxes. You can pass some common properties on the Checkbox.Group level and they will be passed to the checkboxes inside the group.
spacing: This will set how much space should be between the inputs;name: By setting this property on theCheckbox.Grouplevel, you will set it automatically for all the checkboxes in the group;defaultValue: This accepts an array that set thedefaultCheckedproperty for checkboxes which the value exists in the array;value: Same asdefaultValuebut this one sets theisCheckedproperty, making the checkbox group controlled;onChange: Handler that will be executed when any checkbox inside the group receives the event of change.
Code examples
Component variations
Checked or indeterminate
The Checkbox can be rendered as indeterminate or checked, with the isIndeterminate, and isChecked or defaultChecked properties.
Note that providing the isChecked makes it a controlled input, requiring an onChange handler.
The Checkbox can be rendered as disabled with the isDisabled property.
Content guidelines
- Use direct, succinct copy that helps the user to successfully complete the form
- Do not use punctuation for labels
- Use sentence style caps (in which only the first word of a sentence or term is capitalized)
Accessibility
- To ensure
Checkboxmeets accessibility standards, providenameandid; - When using
Checkbox.Groupit should be wrapped in a<FormControl as="fieldset">and have a<FormControl.Label as="legend">.
Props
Props Checkbox
- Name
aria-label
DescriptionValue to be set as aria-label if not passing a children
string - Name
className
DescriptionCSS class to be appended to the root element
string - Name
defaultChecked
DescriptionDefines initial checked state for an uncontrolled component
falsetrue - Name
helpText
DescriptionOptional text to be added as help text bellow the label
string - Name
id
DescriptionSets the id of the input
string - Name
inputProps
DescriptionAdditional props that are passed to the input element
Partial<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>> - Name
isChecked
DescriptionDefines if the element is checked, onChange will be required
falsetrue - Name
isDisabled
DescriptionApplies disabled styles
falsetrue - Name
isIndeterminate
DescriptionDefines if the state is indeterminate
falsetrue - Name
isInvalid
DescriptionApplies invalid styles
falsetrue - Name
isRequired
DescriptionValidate the input
falsetrue - Name
label
string - Name
name
DescriptionSet the name of the input
string - Name
onBlur
DescriptionAllows to listen to an event when an element loses focus
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement> - Name
onChange
DescriptionAllows to listen to an input’s change in value
ChangeEventHandler<HTMLInputElement> - Name
onFocus
DescriptionAllows to listen to an event when an element get focused
FocusEventHandler<HTMLInputElement | HTMLTextAreaElement> - Name
onKeyDown
DescriptionAllows to listen to an event when a key is pressed
KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement> - Name
resize
DescriptionSets whether an element is resizable, and if so, in which directions
"none""both""horizontal""vertical" - Name
testId
DescriptionA [data-test-id] attribute used for testing purposes
string - Name
value
DescriptionSet the value of the input
string - Name
willBlurOnEsc
DescriptionBoolean property that allows to blur on escape
falsetrue
Props Group
- Name
children(required)
DescriptionElements that should be in the group
ReactNode - Name
className
DescriptionCSS class to be appended to the root element
string - Name
defaultValue
DescriptionArray of values of the checkboxes that should be checked for uncontrolled inputs
string[] - Name
name
DescriptionName that will be assigned to all checkboxes inside the group, unless a different name is passed to the checkbox
string - Name
onBlur
DescriptionHandler that will be triggered when any checkbox inside the group loses focus
FocusEventHandler<HTMLInputElement> - Name
onChange
DescriptionHandler that will be triggered when any checkbox inside the group has their checked state changed
ChangeEventHandler<HTMLInputElement> - Name
testId
DescriptionA [data-test-id] attribute used for testing purposes
string - Name
value
DescriptionArray of values of the checkboxes that should be checked for controlled inputs
string[]