Checkbox
Checkboxes are most commonly used to give users a way to make a range of selections (zero, one, or multiple).
Example
Live Editor
<div style={{ display: 'flex', alignItems: 'center' }}> <Checkbox id="checkbox" label="I've read the terms and conditions" /> </div>
Result
Loading...
Usage Rules
Do:
- Have options unchecked by default
- Use if multiple options can be selected
- Use as a single option with yes/no or on/off answer
- Layout your option list vertically, with one choice per line
- Use active wording and avoid negations in labels
- Use in parent-child combination with other checkboxes
Don’t:
- Use as action buttons
- Use if only one option can be selected
Variants
Disabled
Live Editor
<div style={{ display: 'flex', alignItems: 'center' }}> <Checkbox id="checkbox-disabled" label="You can't click me" disabled /> </div>
Result
Loading...
Helper Text
You can add an extra description by adding helperText
.
Live Editor
function check() { const [termsChecked, setTermsChecked] = useState(false); const handleChange = (e) => { setTermsChecked(e.target.checked) } return ( <> <p>Please select your terms</p> <Checkbox label="In-app revenue (from in-app purchases)" helperText="You need to map events which generate revenue to share this data." /> <br/> <Checkbox label="I agree to the Terms and Conditions" helperText="It’s required to agree to the terms before enabling this feature." checked={termsChecked} onChange={(e) => handleChange(e)} required /> </> ) }
Result
Loading...
Indeterminate
A Checkbox can be in an indeterminate state, controlled using the indeterminate
prop. Using it changes the Checkbox's visual appearance, but not its value. The indeterminate
prop takes precedence over checked
prop.
Live Editor
<div style={{ display: 'flex', alignItems: 'center' }}> <Checkbox indeterminate={true} id="indeterminate" label="Indeterminate" /> </div>
Result
Loading...
Label Info Tooltip
You can add more information for label by adding labelIconTooltip
.
The tooltip content
can either be pure text or any rich content wrapped in a React component. The tooltip position
is used to define the positioning of the tooltip
When the tooltip content
is not provided, the label icon will be not shown.
Live Editor
<> <p>Please select your terms</p> <Checkbox label="In-app revenue (from in-app purchases)" helperText="You need to map events which generate revenue to share this data." /> <br/> <Checkbox label="I agree to the Terms and Conditions" helperText="It’s required to agree to the terms before enabling this feature." labelIconTooltip={{ content: 'I agree to the Terms and Conditions', position: 'right' }} /> </>
Result
Loading...
Ref
Live Editor
function refTest() { const checkboxRef = React.createRef(); const [value, setValue] = useState(false); const handleChange = () => { checkboxRef.current.checked = !checkboxRef.current.checked; }; return ( <> <Checkbox id="checkbox-ref" ref={checkboxRef} checked={true} /> <Button onClick={handleChange} label="Check me!" /> </> ); }
Result
Loading...
Props
Name | Type | Default |
---|---|---|
disabled Native HTML attribute: Link |
| — |
css Add custom styles to this component. Use with caution. Learn more here: Link |
| — |
inputFieldCss |
| — |
label The label for the checkbox |
| — |
aria-label Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link |
| — |
aria-labelledby Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link |
| — |
id Native HTML attribute: Link .
Internally, this component uses a random id. We use it to associate an input with a label element.
As the random id might break snapshot tests it can be overridden by setting an explicit id. |
| — |
onKeyDown Keyboard event callback |
| — |
indeterminate Don't use this prop together with the 'checked' prop |
| false |
checked Native HTML attribute: Link |
| — |
required Native HTML attribute: Link |
| — |
readOnly Native HTML attribute: Link |
| — |
onChange Native HTML callback: Link |
| — |
value Native HTML attribute: Link |
| — |
helperText HelperText for checkbox |
| — |
tabIndex Tab index |
| — |
labelIconTooltip The label info tooltip icon |
| — |
ref |
| — |
key |
| — |
data-{foo} Data attributes can be used by testing libraries to retrieve components or assert their existence |
| — |
* - the prop is required. |