---
summary: 送信して確定する ON/OFF や複数選択に使うチェックボックス
category: Forms
---

# Checkbox

ラベル付きのチェックボックスで、ある項目を ON にするかどうかや、複数の選択肢から任意の数を選ばせるときに使います。
素の `<input type="checkbox">` の代わりに使います。
即時に反映する設定には Switch、選択肢から 1 つだけを選ばせる場合は RadioGroup + Radio を使ってください。

## 基本の使い方

```tsx
import { Checkbox } from 'wip-ui'

<Checkbox>利用規約に同意する</Checkbox>
```

## 使う場面

- 「ある項目を ON にするか」を選ばせるとき
- 複数の選択肢から任意の数を選ばせるとき
- 「全選択」のチェックボックスで、子項目の一部だけが選択されていることを示すとき

## 使い方

### 状態

- [should] 権限不足や条件未達で変更できない場合は isDisabled を指定する

### 複数選択

- 複数のチェックボックスをまとめて、グループとして名前を付けるコンポーネント（CheckboxGroup）はない

### 親子関係（全選択）

- [should] 子項目の一部だけが選択されている場合は、親のチェックボックスに isIndeterminate を指定する
- [should] 親を ON にしたらすべての子を ON に、OFF にしたらすべての子を OFF にする
- [should] isIndeterminate の親を押したときは、すべての子を OFF にする

## アクセシビリティ

- [must] 見えるラベルを付けない場合は、aria-label でチェックボックスの名前を付ける

## 実装

- 親子の選択状態は自動では連動しない。onChange で受け取り、各チェックボックスの isSelected と isIndeterminate を制御する

## Props（自動生成）

型定義から生成した props の一覧です。react-aria-components から引き継いだ props の説明は英語です。DOM の汎用的な属性・イベントは省略しています。

### Checkbox

| 名前 | 型 | 既定値 | 説明 |
|---|---|---|---|
| children（必須） | ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
| inputRef | RefObject<HTMLInputElement \| null> | - | A ref for the HTML input element. |
| isIndeterminate | boolean | - | Indeterminism is presentational only. The indeterminate visual representation remains regardless of user interaction. |
| value | string | - | The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |
| defaultSelected | boolean | - | Whether the element should be selected (uncontrolled). |
| isSelected | boolean | - | Whether the element should be selected (controlled). |
| onChange | ((isSelected: boolean) => void) | - | Handler that is called when the element's selection state changes. |
| isDisabled | boolean | - | Whether the input is disabled. |
| isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
| isRequired | boolean | - | Whether user input is required on the input before form submission. |
| isInvalid | boolean | - | Whether the input value is invalid. |
| validate | ((value: boolean) => true \| ValidationError \| null) | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. |
| autoFocus | boolean | - | Whether the element should receive focus on render. |
| name | string | - | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| form | string | - | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). |
| aria-controls | string | - | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| excludeFromTabOrder | boolean | - | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. |
| id | string | - | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). |
| aria-label | string | - | Defines a string value that labels the current element. |
| aria-labelledby | string | - | Identifies the element (or elements) that labels the current element. |
| aria-describedby | string | - | Identifies the element (or elements) that describes the object. |
| aria-details | string | - | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| aria-errormessage | string | - | Identifies the element that provides an error message for the object. |
| onPress | ((e: PressEvent) => void) | - | Handler that is called when the press is released over the target. |
| onPressStart | ((e: PressEvent) => void) | - | Handler that is called when a press interaction starts. |
| onPressEnd | ((e: PressEvent) => void) | - | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. |
| onPressChange | ((isPressed: boolean) => void) | - | Handler that is called when the press state changes. |
| onPressUp | ((e: PressEvent) => void) | - | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. |
| onClick | ((e: MouseEvent<FocusableElement, MouseEvent>) => void) | - | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides  additional event details for non-mouse interactions. |
| validationBehavior | "native" \| "aria" | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
| className | ClassNameOrFunction<CheckboxRenderProps> | - | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. |
| style | StyleOrFunction<CheckboxRenderProps> | - | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. |
| slot | string \| null | - | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |