---
title: 'Form.Checkbox'
type: 'component'
components:
- FormCheckbox
- CheckboxControl
- FormCheckboxSet
categories:
- Forms
status: 'New'
designStatus: 'Done'
devStatus: 'Done'
notes: |

---

A simple checkbox for use with `Form.CheckboxSet`.

Note: extra props added to this component are passed as attributes to the
underlying `input` node. See MDN for documentation on available
[input attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes).


## Controlled Standalone Usage

```jsx live
() => {
  const [isChecked, setChecked] = useState(false);
  const handleChange = e => setChecked(e.target.checked);
  return (
    <Form.Checkbox checked={isChecked} onChange={handleChange}>
      I want pizza.
    </Form.Checkbox>
  );
}
```

## Unlabeled control

```jsx live
() => {
  const [isChecked, setChecked] = useState(false);
  const handleChange = e => setChecked(e.target.checked);
  return (
    <CheckboxControl
      checked={isChecked}
      onChange={handleChange}
      aria-label="Checkbox"
    />
  );
}
```

## Controlled Group Usage with useCheckboxSetValues

`useCheckboxSetValues(initialValues[])` returns an array: `[state, dispatchers]`.

`dispatchers` includes `add(value)` `remove(value)` `set(values[])` and `clear()`

```jsx live
() => {

  const [colorValues, { add, remove }] = useCheckboxSetValues(['green']);

  const handleChange = e => {
    if (e.target.checked) {
      add(e.target.value);
    } else {
      remove(e.target.value);
    }
  }
  return (
    <Form.Group>
      <Form.Label>Which Color?</Form.Label>
      <Form.CheckboxSet
        name="colors"
        onChange={handleChange}
        value={colorValues}
      >
        <Form.Checkbox value="red">Red</Form.Checkbox>
        <Form.Checkbox value="green">Green</Form.Checkbox>
        <Form.Checkbox value="blue">Blue</Form.Checkbox>
        <Form.Checkbox value="cyan" disabled>Cyan</Form.Checkbox>
      </Form.CheckboxSet>
    </Form.Group>
  );
}
```



### Uncontrolled Usage

```jsx live
<Form.Group>
  <Form.Label>Which Color?</Form.Label>
  <Form.CheckboxSet
    name="color-two"
    onChange={(e) => console.log(e.target.value)}
    defaultValue={['green']}
  >
    <Form.Checkbox value="red">Red</Form.Checkbox>
    <Form.Checkbox value="green">Green</Form.Checkbox>
    <Form.Checkbox value="blue">Blue</Form.Checkbox>
    <Form.Checkbox value="cyan" disabled>Cyan</Form.Checkbox>
  </Form.CheckboxSet>
</Form.Group>
```

### Indeterminate Usage

```jsx live
() => {
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };

  const handleCheckAllChange = e => {
    e.target.checked ? set(allCheeseOptions) : clear();
  };

  const allChecked = allCheeseOptions.every(value => checkedCheeses.includes(value));
  const someChecked = allCheeseOptions.some(value => checkedCheeses.includes(value));
  const isIndeterminate = someChecked && !allChecked;

  return (
    <>
      <div className="d-flex">
        <Form.Checkbox
          checked={allChecked}
          isIndeterminate={isIndeterminate}
          onChange={handleCheckAllChange}
        >
          All the cheese
        </Form.Checkbox>
      </div>
      <Form.CheckboxSet
      	name="color-six"
        className="p-2"
        value={checkedCheeses}
        onChange={handleChange}
      >
        <Form.Checkbox value="swiss">Swiss</Form.Checkbox>
        <Form.Checkbox value="cheddar">Cheddar</Form.Checkbox>
        <Form.Checkbox value="pepperjack">Pepperjack</Form.Checkbox>
      </Form.CheckboxSet>
    </>
  );
}
```

### Inline layout

```jsx live
<Form.Group>
  <Form.Label>Which Color?</Form.Label>
  <Form.CheckboxSet
    name="color-three"
    onChange={(e) => console.log(e.target.value)}
    defaultValue={['green']}
    isInline
  >
    <Form.Checkbox value="red">Red</Form.Checkbox>
    <Form.Checkbox value="green">Green</Form.Checkbox>
    <Form.Checkbox value="blue">Blue</Form.Checkbox>
    <Form.Checkbox value="cyan" disabled>Cyan</Form.Checkbox>
  </Form.CheckboxSet>
</Form.Group>
```

## Validation

### Group Level Validation

```jsx live
<Form.Group isInvalid>
  <Form.Label>Which Color?</Form.Label>
  <Form.CheckboxSet
    name="color-five"
    onChange={(e) => console.log(e.target.value)}
  >
    <Form.Checkbox value="red">Red</Form.Checkbox>
    <Form.Checkbox value="green">Green</Form.Checkbox>
    <Form.Checkbox value="blue">Blue</Form.Checkbox>
    <Form.Checkbox value="cyan" disabled>Cyan</Form.Checkbox>
  </Form.CheckboxSet>
  <Form.Control.Feedback>
    Please choose an option.
  </Form.Control.Feedback>
</Form.Group>
```

### Individual option validation

```jsx live
<Form.Group>
  <Form.Label>Which Color?</Form.Label>
  <Form.CheckboxSet name="color-four">
    <Form.Checkbox
      value="red"
      description="Red's cool"
    >
      Red
    </Form.Checkbox>
    <Form.Checkbox
      value="green"
      description="Excellent choice"
      isValid
    >
      Green
    </Form.Checkbox>
    <Form.Checkbox
      value="blue"
      description="Poor choice"
      isInvalid
    >
      Blue
    </Form.Checkbox>
    <Form.Checkbox
      value="cyan"
      disabled
    >
      Cyan
    </Form.Checkbox>
  </Form.CheckboxSet>
</Form.Group>
```

## Label Position

The label is positioned to the right of the checkbox control by default. The label can be rendered on the left instead
by passing the `floatLabelLeft` prop.

```jsx live
<Form.Group>
  <Form.CheckboxSet name="color-single">
    <Form.Checkbox value="red" floatLabelLeft>Red</Form.Checkbox>
  </Form.CheckboxSet>
</Form.Group>
```
