## Usage

When used by itself, the `<Checkbox />` component is merely a toggle between checked and not checked. The checkbox will automatically render a visibly hidden `<input type="checkbox">` to ensure events propagate correctly.

When using multiple checkboxes together, they allow the user to select any number of values from several options, including zero, one or multiple.

```tsx live
<Checkbox>Accept terms and conditions</Checkbox>
```

### Guidelines

- In a "create"-form (new data being entered), no checkboxes should be checked initially
- Prefer placing the checkboxes underneath each other to aid scannability
- List radios in a logical order, e.g:
  - Alphabetically
  - Numerically
  - Time-based
  - Most to least likely to be checked

## Controlled

The checkbox can be uncontrolled or controlled. Use the `checked` prop, along with `onChange` to take control of the state. When controlling checkboxes with `useState`, prefer using the [functional updates syntax](https://reactjs.org/docs/hooks-reference.html#functional-updates). In most cases, [React recommends using controlled components](https://reactjs.org/docs/uncontrolled-components.html) to implement forms. If you are using a controlled input the `checked` value can't be `undefined` it must be a `true|false` otherwise React will display an error in the console alerting that the component was changed from uncontrolled to controlled.

Tip: Wrap your checkboxes with the [CheckboxGroup](#checkbox-group) component to manage the state more easily, and get the recommended layout out of the box.

```tsx live
const [[cb1, cb2], setCheckedItems] = useState([false, false]);

return (
  <Flex as="form" flexDirection="column" gap="small">
    <Checkbox checked={cb1} onChange={() => setCheckedItems(([cb1, cb2]) => [!cb1, cb2])}>
      Checkbox 1
    </Checkbox>
    <Checkbox checked={cb2} onChange={() => setCheckedItems(([cb1, cb2]) => [cb1, !cb2])}>
      Checkbox 2
    </Checkbox>
  </Flex>
);
```

## Indeterminate

The checkbox also supports `indeterminate` state.

```tsx live
const [checkedItems, setCheckedItems] = useState([false, false]);
const [cb1, cb2] = checkedItems;
const allChecked = checkedItems.every(Boolean);
const isIndeterminate = checkedItems.some(Boolean) && !allChecked;

return (
  <Flex as="form" flexDirection="column" gap="medium">
    <Checkbox
      checked={allChecked}
      onChange={() => (allChecked ? setCheckedItems([false, false]) : setCheckedItems([true, true]))}
      indeterminate={isIndeterminate}
    >
      Parent Checkbox
    </Checkbox>

    <Flex paddingLeft="medium" flexDirection="column" gap="small">
      <Checkbox checked={cb1} onChange={() => setCheckedItems(([cb1, cb2]) => [!cb1, cb2])}>
        Child Checkbox 1
      </Checkbox>
      <Checkbox checked={cb2} onChange={() => setCheckedItems(([cb1, cb2]) => [cb1, !cb2])}>
        Child Checkbox 2
      </Checkbox>
    </Flex>
  </Flex>
);
```

## Disabled

```tsx live
<Flex as="form" flexDirection="column" gap="small">
  <Checkbox disabled>Disabled</Checkbox>
  <Checkbox checked disabled>
    Checked + disabled
  </Checkbox>
</Flex>
```

## Size

There are two checkbox sizes, `small` and `medium` (default).

```tsx live
<Flex as="form" flexDirection="column" gap="small">
  <Checkbox size="small">Small checkbox</Checkbox>
  <Checkbox>Medium checkbox (default)</Checkbox>
</Flex>
```

## Custom children

To customise or add more information to the checkbox label, you can pass in any other component via `children`.

```tsx live
<Checkbox>
  <Flex flexDirection="column">
    <Text fontWeight="bold">Bold label</Text>
    <Text fontSize="xsmall" lineHeight="tight" color="neutralSubtle">
      Sub text
    </Text>
  </Flex>
</Checkbox>
```

## Build a custom checkbox

In rare cases when you need to create a custom checkbox, you can use the `<CheckboxPrimitive />` component. Don't forget to use a `<label>` in conjunction, with a `htmlFor="CHECKBOX_PRIMITIVE_ID_HERE"` for accessibility.

```tsx live
const [checked, setChecked] = useState(false);

return (
  <Flex
    as="label"
    htmlFor="custom-checkbox-1"
    backgroundColor={checked ? 'informativeSubtle' : 'neutralSubtle'}
    alignItems="center"
    padding="medium"
    borderRadius="medium"
    gap="medium"
  >
    <CheckboxPrimitive id="custom-checkbox-1" checked={checked} onChange={() => setChecked((checked) => !checked)} />
    <Text>This is a custom component using the CheckboxPrimitive</Text>
  </Flex>
);
```

## Checkbox group

The `<CheckboxGroup />` component is a styled context provider to help manage the state of a controlled group of checkboxes, using the React Context API. Each `<Checkbox />` **must** have a unique `value` set.

It is recommended to wrap your checkbox group with a [Fieldset](/packages/fieldset/), which lets you add a legend and will be read out as a "group" by some screen readers.

```tsx live
const [checkedValue, setCheckedValue] = useState(['apple']);

return (
  <Flex flexDirection="column" gap="medium">
    <Fieldset legend="Your favourite fruits" legendStyle="group">
      <CheckboxGroup value={checkedValue} onInputChange={setCheckedValue}>
        <Checkbox value="apple">Apple</Checkbox>
        <Checkbox value="banana">Banana</Checkbox>
        <Checkbox value="orange">Orange</Checkbox>
      </CheckboxGroup>
    </Fieldset>

    <Divider />

    <Text fontFamily="mono">checkedValue: {JSON.stringify(checkedValue)}</Text>
  </Flex>
);
```

### Size

Use the `size` prop to control the input size of the nested checkboxes of the checkbox group.

```tsx live
const [checkedValue, setCheckedValue] = useState(['apple']);

return (
  <CheckboxGroup size="small" value={checkedValue} onInputChange={setCheckedValue}>
    <Checkbox value="apple">Apple</Checkbox>
    <Checkbox value="banana">Banana</Checkbox>
    <Checkbox value="orange">Orange</Checkbox>
  </CheckboxGroup>
);
```

### Horizontal

In rare cases you can add the `horizontal` prop to make the radios in the checkbox group stack horizontally. However – it's recommended to use the default vertical layout for the best readability and experience.

```tsx live
const [checkedValue, setCheckedValue] = useState(['apple']);

return (
  <CheckboxGroup horizontal value={checkedValue} onInputChange={setCheckedValue}>
    <Checkbox value="apple">Apple</Checkbox>
    <Checkbox value="banana">Banana</Checkbox>
    <Checkbox value="orange">Orange</Checkbox>
  </CheckboxGroup>
);
```

### Validation

If you need validation on a checkbox group you can use the same validation props as [Field](/packages/field/); `invalid` and `message`.

```tsx live
<CheckboxGroup
  invalid={true}
  message="At least one is required"
  value={['']}
  onInputChange={() => {
    return;
  }}
>
  <Checkbox value="apple">Apple</Checkbox>
  <Checkbox value="banana">Banana</Checkbox>
  <Checkbox value="orange">Orange</Checkbox>
</CheckboxGroup>
```

### Required

Checkbox groups inherit the `required` state from a parent [Fieldset](/packages/fieldset/).

```tsx live
<Fieldset required legend="Required choices" legendStyle="group">
  <CheckboxGroup
    value={['']}
    onInputChange={() => {
      return;
    }}
  >
    <Checkbox value="apple">Apple</Checkbox>
    <Checkbox value="banana">Banana</Checkbox>
    <Checkbox value="orange">Orange</Checkbox>
  </CheckboxGroup>
</Fieldset>
```

### Keep space for message

Just like the [Field](/packages/field/), extra vertical space is added under each checkbox group by default. This prevents layout shifts when a validation message is displayed. You can turn this extra space off by setting `keepSpaceForMessage` to `false`.

A control that allows the user to toggle between checked and not checked.

Checkbox

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

CheckboxGroup

CheckboxPrimitive