---
title: Checkbox
description: "`Checkbox` is a component used for allowing users to select multiple values from multiple options."
links:
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/checkbox
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-checkbox--basic
---

```tsx
<Checkbox>キングダム ハーツ</Checkbox>
```

## Usage

```tsx
import { Checkbox, CheckboxGroup } from "@yamada-ui/react"
```

```tsx
import { Checkbox, CheckboxGroup } from "@/components/ui"
```

```tsx
import { Checkbox, CheckboxGroup } from "@workspaces/ui"
```

```tsx
<Checkbox />
```

```tsx
<CheckboxGroup.Root>
  <CheckboxGroup.Item />
</CheckboxGroup.Root>
```

### Group

```tsx
<CheckboxGroup.Root defaultValue={["sora", "riku"]}>
  <CheckboxGroup.Item value="sora">ソラ</CheckboxGroup.Item>
  <CheckboxGroup.Item value="riku">リク</CheckboxGroup.Item>
  <CheckboxGroup.Item value="kairi">カイリ</CheckboxGroup.Item>
</CheckboxGroup.Root>
```

### Use Items

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return <CheckboxGroup.Root items={items} />
```

### Change Variant

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "Checked", value: "1" },
    { label: "No checked", value: "2" },
  ],
  [],
)

return (
  <VStack>
    <For each={["solid", "subtle", "surface", "outline"]}>
      {(variant) => (
        <CheckboxGroup.Root
          key={variant}
          variant={variant}
          defaultValue={["1"]}
          items={items}
        />
      )}
    </For>
  </VStack>
)
```

### Change Size

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "Checked", value: "1" },
    { label: "No checked", value: "2" },
  ],
  [],
)

return (
  <VStack>
    <For each={["sm", "md", "lg"]}>
      {(size) => (
        <CheckboxGroup.Root
          key={size}
          size={size}
          defaultValue={["1"]}
          items={items}
        />
      )}
    </For>
  </VStack>
)
```

### Set Default Value

To set a default value, set `defaultValue` to an array of values.

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return <CheckboxGroup.Root defaultValue={["sora"]} items={items} />
```

### Default Checked

To default checked, set `defaultChecked` to `true`.

```tsx
<Checkbox defaultChecked>キングダム ハーツ</Checkbox>
```

### Indeterminate

To make indeterminate, set `indeterminate` to `true`.

```tsx preview functional client
const [id0, id1, id2] = useIds()
const [values, setValues] = useState([true, false, false])

const allChecked = values.every(Boolean)
const indeterminate = values.some(Boolean) && !allChecked

return (
  <VStack gap="sm">
    <Checkbox
      checked={allChecked}
      indeterminate={indeterminate}
      inputProps={{ "aria-controls": `${id0} ${id1} ${id2}` }}
      onChange={(ev) =>
        setValues([ev.target.checked, ev.target.checked, ev.target.checked])
      }
    >
      デスティニーアイランド
    </Checkbox>

    <VStack gap="sm" ms="md">
      <Checkbox
        id={id0}
        checked={values[0]}
        onChange={(ev) =>
          setValues([ev.target.checked, values[1]!, values[2]!])
        }
      >
        ソラ
      </Checkbox>
      <Checkbox
        id={id1}
        checked={values[1]}
        onChange={(ev) =>
          setValues([values[0]!, ev.target.checked, values[2]!])
        }
      >
        リク
      </Checkbox>
      <Checkbox
        id={id2}
        checked={values[2]}
        onChange={(ev) =>
          setValues([values[0]!, values[1]!, ev.target.checked])
        }
      >
        カイリ
      </Checkbox>
    </VStack>
  </VStack>
)
```

### Max Selection

To limit the maximum number of selections, set `max` to a number.

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return <CheckboxGroup.Root items={items} max={2} />
```

### Change Direction

To change the direction, set `orientation` to `"horizontal"` or `"vertical"`. The default is `"vertical"`.

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi" },
  ],
  [],
)

return (
  <VStack>
    <For each={["horizontal", "vertical"]}>
      {(orientation) => (
        <CheckboxGroup.Root
          key={orientation}
          orientation={orientation}
          items={items}
        />
      )}
    </For>
  </VStack>
)
```

### Change Shape

To change the shape, set `shape` to `"rounded"` or `"square"`. The default is `"rounded"`.

```tsx
<CheckboxGroup.Root>
  <For each={["rounded", "square"]}>
    {(shape) => (
      <CheckboxGroup.Item key={shape} shape={shape} defaultChecked>
        {toTitleCase(shape)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>
```

### Disable

To disable, set `disabled` to `true`.

```tsx
<CheckboxGroup.Root>
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant) => (
      <CheckboxGroup.Item key={variant} variant={variant} disabled>
        {toTitleCase(variant)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>
```

### Read-Only

To read-only, set `readOnly` to `true`.

```tsx
<CheckboxGroup.Root>
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant) => (
      <CheckboxGroup.Item
        key={variant}
        variant={variant}
        readOnly
        defaultChecked
      >
        {toTitleCase(variant)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>
```

### Invalid

To make invalid, set `invalid` to `true`.

```tsx
<CheckboxGroup.Root>
  <For each={["solid", "subtle", "surface", "outline"]}>
    {(variant) => (
      <CheckboxGroup.Item key={variant} variant={variant} invalid>
        {toTitleCase(variant)}
      </CheckboxGroup.Item>
    )}
  </For>
</CheckboxGroup.Root>
```

### Change Border Color

To change the border color, set `focusBorderColor` or `errorBorderColor` to a color value.

```tsx
<CheckboxGroup.Root>
  <CheckboxGroup.Item value="default">Default Border Color</CheckboxGroup.Item>
  <CheckboxGroup.Item focusBorderColor="green.500" value="custom">
    Custom Border Color
  </CheckboxGroup.Item>
  <CheckboxGroup.Item errorBorderColor="orange.500" invalid value="error">
    Custom Error Border Color
  </CheckboxGroup.Item>
</CheckboxGroup.Root>
```

### Customize Icon

To customize icon, set `checkedIcon` to a `ReactNode`.

```tsx
const items = useMemo<CheckboxGroup.Item[]>(
  () => [
    { label: "ソラ", value: "sora" },
    { label: "リク", value: "riku" },
    { label: "カイリ", value: "kairi", checkedIcon: <HeartIcon /> },
  ],
  [],
)

return <CheckboxGroup.Root checkedIcon={<KeyIcon />} items={items} />
```

### Use Custom Component

```tsx
const { getInputProps, getLabelProps, getRootProps } = useCheckboxGroup({
  defaultValue: ["sora"],
  max: 2,
})

const CustomCheckbox = ({ children, ...rest }) => {
  return (
    <Box
      as="label"
      css={{
        "&:has(input:checked)": {
          bg: "colorScheme.solid",
          borderColor: "colorScheme.solid",
          color: "colorScheme.contrast",
        },
        "&:has(input:disabled)": {
          layerStyle: "disabled",
        },
        alignItems: "center",
        borderWidth: "1px",
        display: "flex",
        h: "10",
        px: "3",
        rounded: "l2",
      }}
      {...getLabelProps()}
    >
      <Box as="input" {...getInputProps(rest)} />
      {children}
    </Box>
  )
}

return (
  <HStack {...getRootProps()}>
    <CustomCheckbox value="sora">ソラ</CustomCheckbox>
    <CustomCheckbox value="riku">リク</CustomCheckbox>
    <CustomCheckbox value="kairi">カイリ</CustomCheckbox>
  </HStack>
)
```

### Control

```tsx
const [checked, { toggle }] = useBoolean(false)

return (
  <Checkbox checked={checked} onChange={toggle}>
    ソラ
  </Checkbox>
)
```

## Uses Components & Hooks

<Uses name="checkbox" />

## Used By Components & Hooks

<UsedBy name="checkbox" />

## Props

### Checkbox

| Prop                | Default   | Type                                                                                                                                                                        | Description                                                   |
| ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `as`                | -         | `As`                                                                                                                                                                        | The HTML element to render.                                   |
| `asChild`           | -         | `boolean`                                                                                                                                                                   | Merges its props onto its immediate child.                    |
| `css`               | -         | `CSSObject \| CSSObject[]`                                                                                                                                                  | The CSS object.                                               |
| `colorScheme`       | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                                   | Set color scheme variables.                                   |
| `size`              | `"md"`    | `"lg" \| "md" \| "sm"`                                                                                                                                                      | The size of the component.                                    |
| `variant`           | `"solid"` | `"outline" \| "solid" \| "subtle" \| "surface"`                                                                                                                             | The variant of the component.                                 |
| `checked`           | -         | `boolean`                                                                                                                                                                   | If `true`, the checkbox will be checked.                      |
| `checkedIcon`       | -         | `ReactNode`                                                                                                                                                                 | The icon to display in the checkbox when it is checked.       |
| `defaultChecked`    | `false`   | `boolean`                                                                                                                                                                   | If `true`, the checkbox will be initially checked.            |
| `disabled`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be disabled.                        |
| `errorBorderColor`  | -         | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is invalid.                   |
| `focusBorderColor`  | -         | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is focused.                   |
| `id`                | -         | `string`                                                                                                                                                                    | id assigned to input.                                         |
| `indeterminate`     | `false`   | `boolean`                                                                                                                                                                   | If `true`, the checkbox will be indeterminate.                |
| `indeterminateIcon` | -         | `ReactNode`                                                                                                                                                                 | The icon to display in the checkbox when it is indeterminate. |
| `indicatorProps`    | -         | `CheckboxIndicatorProps`                                                                                                                                                    | Props for the indicator component.                            |
| `inputProps`        | -         | `HTMLStyledProps<"input">`                                                                                                                                                  | Props for the input element.                                  |
| `invalid`           | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be invalid.                         |
| `labelProps`        | -         | `CheckboxLabelProps`                                                                                                                                                        | Props for the label component.                                |
| `name`              | -         | `string`                                                                                                                                                                    | The name of the input field in a checkbox.                    |
| `onBlur`            | -         | `FocusEventHandler<HTMLInputElement>`                                                                                                                                       | The callback invoked when the checkbox is blurred.            |
| `onChange`          | -         | `ChangeEventHandler<HTMLInputElement>`                                                                                                                                      | The callback invoked when the checked state changes.          |
| `onFocus`           | -         | `FocusEventHandler<HTMLInputElement>`                                                                                                                                       | The callback invoked when the checkbox is focused.            |
| `readOnly`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be readonly.                        |
| `required`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be required.                        |
| `rootProps`         | -         | `HTMLStyledProps<"label">`                                                                                                                                                  | Props for the label element.                                  |
| `value`             | -         | `Y`                                                                                                                                                                         | The value of the checkbox.                                    |

### CheckboxGroup.Root

| Prop               | Default   | Type                                                                                                                                                                        | Description                                                            |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `as`               | -         | `As`                                                                                                                                                                        | The HTML element to render.                                            |
| `asChild`          | -         | `boolean`                                                                                                                                                                   | Merges its props onto its immediate child.                             |
| `css`              | -         | `CSSObject \| CSSObject[]`                                                                                                                                                  | The CSS object.                                                        |
| `colorScheme`      | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                                   | Set color scheme variables.                                            |
| `size`             | `"md"`    | `"lg" \| "md" \| "sm"`                                                                                                                                                      | The size of the component.                                             |
| `variant`          | `"solid"` | `"outline" \| "solid" \| "subtle" \| "surface"`                                                                                                                             | The variant of the component.                                          |
| `align`            | -         | `"-moz-initial" \| "anchor-center" \| "baseline" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "normal" ...`                              | The CSS `align-items` property.                                        |
| `basis`            | -         | `"-moz-fit-content" \| "-moz-initial" \| "-moz-max-content" \| "-moz-min-content" \| "-webkit-auto" \| "0.5" \| "1.5" \| "1" \| "1/12" \| "1/2" ...`                        | The CSS `flex-basis` property.                                         |
| `checkedIcon`      | -         | `string \| number \| bigint \| boolean \| ReactElement<unknown, string \| JSXElementConstructor<any>> \| Iterable<ReactNode> \| ReactPortal \| Promise<...>`                | The icon to display in the checkbox when it is checked.                |
| `defaultValue`     | `[]`      | `Y[]`                                                                                                                                                                       | The initial value of the checkbox group.                               |
| `direction`        | -         | `"-moz-initial" \| "column-reverse" \| "column" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "row-reverse" \| "row" \| "unset" ...`                           | The CSS `flex-direction` property.                                     |
| `disabled`         | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be disabled.                                 |
| `errorBorderColor` | -         | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is invalid.                            |
| `focusBorderColor` | -         | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is focused.                            |
| `invalid`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be invalid.                                  |
| `items`            | `[]`      | `CheckboxGroupItem<Y>[]`                                                                                                                                                    | If provided, generate options based on items.                          |
| `justify`          | -         | `"-moz-initial" \| "center" \| "end" \| "flex-end" \| "flex-start" \| "inherit" \| "initial" \| "left" \| "normal" \| "revert-layer" ...`                                   | The CSS `justify-content` property.                                    |
| `max`              | -         | `number`                                                                                                                                                                    | The maximum number of checkboxes that can be checked.                  |
| `onChange`         | -         | `(value: Y[]) => void`                                                                                                                                                      | The callback fired when any children checkbox is checked or unchecked. |
| `readOnly`         | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be readonly.                                 |
| `required`         | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be required.                                 |
| `shrink`           | -         | `"-moz-initial" \| "inherit" \| "initial" \| "revert-layer" \| "revert" \| "unset" \| number & {} ...`                                                                      | The CSS `flex-shrink` property.                                        |
| `value`            | -         | `Y[]`                                                                                                                                                                       | The value of the checkbox group.                                       |
| `wrap`             | -         | `"-moz-initial" \| "inherit" \| "initial" \| "nowrap" \| "revert-layer" \| "revert" \| "unset" \| "wrap-reverse" \| "wrap" ...`                                             | The CSS `flex-wrap` property.                                          |

### CheckboxGroup.Item

| Prop                | Default   | Type                                                                                                                                                                        | Description                                                   |
| ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `as`                | -         | `As`                                                                                                                                                                        | The HTML element to render.                                   |
| `asChild`           | -         | `boolean`                                                                                                                                                                   | Merges its props onto its immediate child.                    |
| `css`               | -         | `CSSObject \| CSSObject[]`                                                                                                                                                  | The CSS object.                                               |
| `colorScheme`       | -         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                                   | Set color scheme variables.                                   |
| `size`              | `"md"`    | `"lg" \| "md" \| "sm"`                                                                                                                                                      | The size of the component.                                    |
| `variant`           | `"solid"` | `"outline" \| "solid" \| "subtle" \| "surface"`                                                                                                                             | The variant of the component.                                 |
| `checked`           | -         | `boolean`                                                                                                                                                                   | If `true`, the checkbox will be checked.                      |
| `checkedIcon`       | -         | `ReactNode`                                                                                                                                                                 | The icon to display in the checkbox when it is checked.       |
| `defaultChecked`    | `false`   | `boolean`                                                                                                                                                                   | If `true`, the checkbox will be initially checked.            |
| `disabled`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be disabled.                        |
| `errorBorderColor`  | -         | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is invalid.                   |
| `focusBorderColor`  | -         | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is focused.                   |
| `id`                | -         | `string`                                                                                                                                                                    | id assigned to input.                                         |
| `indeterminate`     | `false`   | `boolean`                                                                                                                                                                   | If `true`, the checkbox will be indeterminate.                |
| `indeterminateIcon` | -         | `ReactNode`                                                                                                                                                                 | The icon to display in the checkbox when it is indeterminate. |
| `indicatorProps`    | -         | `CheckboxIndicatorProps`                                                                                                                                                    | Props for the indicator component.                            |
| `inputProps`        | -         | `HTMLStyledProps<"input">`                                                                                                                                                  | Props for the input element.                                  |
| `invalid`           | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be invalid.                         |
| `labelProps`        | -         | `CheckboxLabelProps`                                                                                                                                                        | Props for the label component.                                |
| `name`              | -         | `string`                                                                                                                                                                    | The name of the input field in a checkbox.                    |
| `onBlur`            | -         | `FocusEventHandler<HTMLInputElement>`                                                                                                                                       | The callback invoked when the checkbox is blurred.            |
| `onChange`          | -         | `ChangeEventHandler<HTMLInputElement>`                                                                                                                                      | The callback invoked when the checked state changes.          |
| `onFocus`           | -         | `FocusEventHandler<HTMLInputElement>`                                                                                                                                       | The callback invoked when the checkbox is focused.            |
| `readOnly`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be readonly.                        |
| `required`          | `false`   | `boolean`                                                                                                                                                                   | If `true`, the field will be required.                        |
| `rootProps`         | -         | `HTMLStyledProps<"label">`                                                                                                                                                  | Props for the label element.                                  |
| `value`             | -         | `Y`                                                                                                                                                                         | The value of the checkbox.                                    |

## Accessibility

The `Checkbox` follows the [WAI-ARIA - Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) for accessibility.

If you are not using `Field.Root`, set `aria-label` or `aria-labelledby` to `CheckboxGroup.Root`.

```tsx
<CheckboxGroup.Root aria-label="Character">
  <CheckboxGroup.Item value="sora">ソラ</CheckboxGroup.Item>
  <CheckboxGroup.Item value="riku">リク</CheckboxGroup.Item>
  <CheckboxGroup.Item value="kairi">カイリ</CheckboxGroup.Item>
</CheckboxGroup.Root>
```

```tsx
<VStack gap="sm">
  <Text as="h3" id="label">
    Character
  </Text>

  <CheckboxGroup.Root aria-labelledby="label">
    <CheckboxGroup.Item value="sora">ソラ</CheckboxGroup.Item>
    <CheckboxGroup.Item value="riku">リク</CheckboxGroup.Item>
    <CheckboxGroup.Item value="kairi">カイリ</CheckboxGroup.Item>
  </CheckboxGroup.Root>
</VStack>
```

### Keyboard Navigation

| Key     | Description                                        | State |
| ------- | -------------------------------------------------- | ----- |
| `Space` | Toggles the checked state of the focused checkbox. | -     |

### ARIA Roles and Attributes

| Component            | Roles and Attributes | Usage                                                                                                                                                                      |
| -------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CheckboxGroup.Root` | `role="group"`       | Indicates that it's a group.                                                                                                                                               |
|                      | `aria-labelledby`    | If `CheckboxGroup.Root` is within a `Field.Root` and `Field.Root` has a `label` or `Field.Label`, sets its `id`.                                                           |
|                      | `aria-describedby`   | If `CheckboxGroup.Root` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`. |
| `input`              | `aria-checked`       | Sets to `"true"` if the checkbox is checked, `"false"` if it is not checked, and `"mixed"` if `indeterminate` is set.                                                      |
|                      | `aria-describedby`   | If `Checkbox` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.           |
|                      | `aria-disabled`      | Sets to `"true"` if `readOnly` is set, or if the checkbox is not checked and `max` is reached in a group.                                                                  |
|                      | `aria-invalid`       | Sets to `"true"` if `invalid` is set.                                                                                                                                      |
|                      | `aria-required`      | Sets to `"true"` if `required` is set.                                                                                                                                     |
| `CheckboxIndicator`  | `aria-hidden`        | Excludes the element from the accessibility tree.                                                                                                                          |