# 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](../RadioGroup/RadioGroup.md) 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](../RadioGroup/RadioGroup.md).

## 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

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `aria-activedescendant` | `string` | No | — | ID of the currently active descendant element. Used for composite widgets like combobox or listbox. @see {@link https... |
| `aria-autocomplete` | `"both" | "inline" | "list" | "none"` | No | — | Indicates the type of autocomplete interaction. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-autocomplete} |
| `aria-controls` | `string` | No | — | Indicates the element that controls the current element. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-controls} |
| `aria-describedby` | `string` | No | — | Identifies the element (or elements) that describes the object. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-... |
| `aria-details` | `string` | No | — | Identifies the element (or elements) that provide a detailed, extended description. @see {@link https://www.w3.org/TR... |
| `aria-expanded` | `Booleanish` | No | — | Indicates whether the element is expanded or collapsed. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-expanded} |
| `aria-label` | `string` | No | — | Defines a string value that labels the current element. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-label} |
| `aria-labelledby` | `string` | No | — | Identifies the element (or elements) that labels the current element. @see {@link https://www.w3.org/TR/wai-aria-1.2/... |
| `aria-required` | `Booleanish` | No | — | Indicates that user input is required before form submission. @see {@link https://www.w3.org/TR/wai-aria-1.2/#aria-re... |
| `checked` | `boolean` | No | — | Determines if the checkbox is checked or not. |
| `defaultChecked` | `boolean` | No | — | Initial checked value of the checkbox. Only use this when you need to pre-populate the checked attribute that is not ... |
| `description` | `ReactNode` | No | — | Additional description of the checkbox. String will be rendered with the default markup. ReactElement will be rendere... |
| `disabled` | `boolean` | No | — | Whether the input is disabled. |
| `id` | `string` | No | — | The unique identifier for the input element. |
| `indeterminate` | `boolean` | No | `false` | When `true` the checkbox to appears in indeterminate. |
| `invalid` | `boolean` | No | — | Whether the checkbox is invalid |
| `label` | `string | ReactElement<unknown, string | JSXElementConstructor<any>>` | No | — | Label that shows up beside the checkbox. String will be rendered with the default markup. ReactElement will be render... |
| `name` | `string` | No | — | The name attribute for the input element. |
| `onBlur` | `(event: FocusEvent<HTMLInputElement, Element>) => void` | No | — | Blur event handler. |
| `onChange` | `(newValue: boolean, event: ChangeEvent<HTMLInputElement>) => void` | No | — | Called when the checkbox value changes. Includes the change event as a second argument. This is the recommended event... |
| `onClick` | `(event: MouseEvent<HTMLInputElement, MouseEvent>) => void` | No | — | Click event handler. |
| `onFocus` | `(event: FocusEvent<HTMLInputElement, Element>) => void` | No | — | Focus event handler. |
| `onMouseDown` | `(event: MouseEvent<HTMLInputElement, MouseEvent>) => void` | No | — | Mouse down event handler. |
| `onMouseUp` | `(event: MouseEvent<HTMLInputElement, MouseEvent>) => void` | No | — | Mouse up event handler. |
| `onPointerDown` | `(event: PointerEvent<HTMLInputElement>) => void` | No | — | Pointer down event handler. |
| `onPointerUp` | `(event: PointerEvent<HTMLInputElement>) => void` | No | — | Pointer up event handler. |
| `ref` | `Ref<HTMLInputElement>` | No | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (... |
| `value` | `string` | No | — | Value of the checkbox. |
