Skip to main content

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

NameTypeDefault
disabled
Native HTML attribute: Link
boolean
css
Add custom styles to this component. Use with caution. Learn more here: Link
SupportedStyleAttributes
inputFieldCss
SupportedStyleAttributes
label
The label for the checkbox
string
aria-label
Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link
string
aria-labelledby
Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link
string
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.
string
onKeyDown
Keyboard event callback
((event: KeyboardEvent<HTMLInputElement>) => void)
indeterminate
Don't use this prop together with the 'checked' prop
boolean
false
checked
Native HTML attribute: Link
boolean
required
Native HTML attribute: Link
boolean
readOnly
Native HTML attribute: Link
boolean
onChange
Native HTML callback: Link
ChangeEventHandler<HTMLInputElement>
value
Native HTML attribute: Link
string | number
helperText
HelperText for checkbox
string
tabIndex
Tab index
number
labelIconTooltip
The label info tooltip icon
Omit<TooltipProps, "children">
ref
Ref<HTMLInputElement>
key
Key | null
data-{foo}
Data attributes can be used by testing libraries to retrieve components or assert their existence
string
* - the prop is required.