# Checkbox

A checkbox lets a user select one or more items from a set of options.

## Design & usage guidelines

A checkbox is a familiar pattern for users who need to choose from a set of
options, or opt in to a single choice. It allows a user to provide boolean
input. It can also be in an indeterminate state when we don't know if the
checkbox is considered checked or not.

A single checkbox, a [Switch](../Switch/Switch.md), and a pair of
[radio buttons](/components/RadioGroup) can seem similar in theory, as all can
represent an either/or decision for the user. Use a switch when the user must
make a decision to turn something on or off, and a single checkbox when a user
is opting in to a choice. A pair of radio buttons can be used to help the user
decide between two discrete options, such as “fixed price” and “per visit”
invoicing options.

Of note: when a single selection is to be made, a Switch should be used rather
than a single Checkbox. Use a Checkbox only when there are multiple selection
options to choose from. when the volume of Radio options is greater than 5 (or
there are otherwise critical vertical space constraints) use Select. when the
labels on a set of Radio options are consistently small (1–2 words), use Chip.

## Related components

* To let people turn a setting on or off instantly, use a
  [Switch](../Switch/Switch.md).
* To present a set of options where people can only make a single choice, use a
  [RadioGroup](/components/RadioGroup).

## Mockup


## Platform considerations

### Event Handlers

While Checkbox exposes mouse event handlers like `onClick`, the recommended way
to access the new value is via the `onChange` prop.

### CheckboxGroup (mobile)

The `<CheckboxGroup>` component is a component that provides a grouping of
checkboxes. It allows you to optionally provide a label which will allow you to
control the Checkbox children with a single parent checkbox. If some but not all
children are checked then the parent checkbox will show the indeterminate state.
An important thing to note is that when using `<CheckboxGroup>` the child
Checkboxes must have a name provided as a prop. This is so the CheckboxGroup is
able to keep track the state of the child Checkboxes. See
[Checkbox/Mobile/Checkbox Group Example](/storybook/mobile/?path=/story/components-selections-checkbox--checkbox-group-example)


## Props

### Mobile

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `accessibilityLabel` | `string` | No | — | Accessibility Label for the checkbox. Defaults to label |
| `assistiveText` | `string` | No | — | Assistive Text, shown under label |
| `checked` | `boolean` | No | — | If the checkbox is checked. This should be set when this is intended as a controlled component |
| `defaultChecked` | `boolean` | No | — | Default value for when the checkbox is uncontrolled |
| `disabled` | `boolean` | No | — | Checkbox is disabled |
| `indeterminate` | `boolean` | No | — | When true, the checkbox is shown as indeterminate |
| `label` | `string` | No | — | Label to be displayed beside the checkbox |
| `name` | `string` | No | — | Name of the checkbox; this is important when using in a form component |
| `onChange` | `((value: boolean) => void) | ((value: boolean) => void)` | No | — | Press handler |