Checkbox

A checkbox is used to choose between two opposite states, often to select/deselect items or enable/disable actions.

Uncontrolled Value

By default, the Checkbox component handles its value uncontrolled. In the uncontrolled variant you can pass in a defaultSelected to check the box by default.

<Checkbox label='Remember me' defaultSelected />

<Checkbox label='Remember me' defaultSelected />

<Checkbox
  label="Remember me"
  defaultSelected
/>

Controlled Value

You can also handle the value of the component in a controlled manner. To do so, you can pass in a value prop as well as an onChange handler to modify the value when the user types.

function Example() {
  const [isSelected, setSelected] = useState(true);

  return (
      <Checkbox
        label='Remember me'
        isSelected={isSelected}
        onChange={setSelected}
        description={`Selected: ${isSelected ? 'true' : 'false'}`}
      />
  );
}

function Example() {
  const [isSelected, setSelected] = useState(true);

  return (
    <Checkbox
      label="Remember me"
      isSelected={isSelected}
      onChange={setSelected}
      description={`Selected: ${
        isSelected ? 'true' : 'false'
      }`}
    />
  );
}

function Example() {
  const [
    isSelected,
    setSelected
  ] = useState(true);

  return (
    <Checkbox
      label="Remember me"
      isSelected={isSelected}
      onChange={setSelected}
      description={`Selected: ${
        isSelected
          ? 'true'
          : 'false'
      }`}
    />
  );
}

Indeterminate

The indeterminate property sets or returns whether the state of a checkbox has changed. Checkboxes actually has three states: true, false and indeterminate which indicates that a checkbox is neither "on" or "off".

<Checkbox label='Remember me' isIndeterminate />

<Checkbox label='Remember me' isIndeterminate />

<Checkbox
  label="Remember me"
  isIndeterminate
/>

Labeling

A Checkbox component should be labeled with a visual text through the label prop. If the Checkbox does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<Checkbox label='Remember me' />

<Checkbox label='Remember me' />

<Checkbox label="Remember me" />

Required

To indicate to the user that the Checkbox is required you can use the isRequired prop.

<Checkbox label='Remember me' isRequired />

<Checkbox label='Remember me' isRequired />

<Checkbox
  label="Remember me"
  isRequired
/>

Validation

The Checkbox component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop. The error message will not be rendered to the user, since a checkbox can only have an error that defines that it needs to be checked. However, it is still useful for screen readers and as such required to be passed in to make the Checkbox invalid. Please localize the error message for internationalization.

function Example() {
  const [isSelected, setSelected] = useState(false);

  return (
    <Checkbox
      label='Remember me'
      isSelected={isSelected}
      onChange={setSelected} 
      errorMessage={!isSelected && 'This field needs to be checked.'}
    />
  );
}

function Example() {
  const [isSelected, setSelected] = useState(false);

  return (
    <Checkbox
      label="Remember me"
      isSelected={isSelected}
      onChange={setSelected}
      errorMessage={!isSelected &&
        'This field needs to be checked.'}
    />
  );
}

function Example() {
  const [
    isSelected,
    setSelected
  ] = useState(false);

  return (
    <Checkbox
      label="Remember me"
      isSelected={isSelected}
      onChange={setSelected}
      errorMessage={!isSelected &&
        'This field needs to be checked.'}
    />
  );
}

Disabled

The Checkbox component can be disabled via the isDisabled prop.

<Checkbox
  label="Remember me"
  defaultSelected={true}
  isDisabled
  description="This field is disabled"
/>

<Checkbox
  label="Remember me"
  defaultSelected={true}
  isDisabled
  description="This field is disabled"
/>

<Checkbox
  label="Remember me"
  defaultSelected={true}
  isDisabled
  description="This field is disabled"
/>

Read Only

The Checkbox component can be marked as read only via the isReadOnly prop.

<Checkbox label="Remember me" defaultSelected={true} isReadOnly />

<Checkbox
  label="Remember me"
  defaultSelected={true}
  isReadOnly
/>

<Checkbox
  label="Remember me"
  defaultSelected={true}
  isReadOnly
/>

Accessibility

In order to support internationalization, provide a localized string to the label or aria-label prop.

API