# 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 `` 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 `` 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>` | 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) => void` | No | — | Blur event handler. | | `onChange` | `(newValue: boolean, event: ChangeEvent) => void` | No | — | Called when the checkbox value changes. Includes the change event as a second argument. This is the recommended event... | | `onClick` | `(event: MouseEvent) => void` | No | — | Click event handler. | | `onFocus` | `(event: FocusEvent) => void` | No | — | Focus event handler. | | `onMouseDown` | `(event: MouseEvent) => void` | No | — | Mouse down event handler. | | `onMouseUp` | `(event: MouseEvent) => void` | No | — | Mouse up event handler. | | `onPointerDown` | `(event: PointerEvent) => void` | No | — | Pointer down event handler. | | `onPointerUp` | `(event: PointerEvent) => void` | No | — | Pointer up event handler. | | `ref` | `Ref` | 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. |