---
name: smarthr-ui-checkbox
description: "Checkboxは、input[type='checkbox']要素の代替としてオン/オフや真偽の状態を入力させるコンポーネントです。5個以下の選択肢から複数の値を選択させるとき、即時反映ではなく送信ボタンで確定させるときに使います。"
metadata:
  version: "1.0.0"
  source: smarthr-design-system
  generated-from: layer1+layer2+layer3
---

input[type='checkbox']要素の代替としてオン/オフや真偽の状態を入力させるコンポーネントです。5個以下の選択肢から複数の値を選択させるとき、即時反映ではなく送信ボタンで確定させるときに使います。

## import

```ts
import { Checkbox } from 'smarthr-ui'
```

## Props

| Props 名 | 型 | デフォルト値 | 必須 | 説明 |
|---|---|---|---|---|
| error | boolean | - | - | チェックボックスにエラーがあるかどうか |
| mixed | boolean | - | - | `true` のとき、チェック状態を `mixed` にする |

## 実装ルール

### a11y-prohibit-checkbox-or-radio-in-table-cell
テーブルセル（Th, Td）内に直接 Checkbox, RadioButton を配置することを禁止するルールです。<br /> SmartHR UI には、デフォルトでアクセシブルネームを設定する TdCheckbox, ThCheckbox, TdRadioButton といったより適切なコンポーネントが用意されています。

❌ NG:

```jsx
// Td, Th内にCheckbox, RadioButtonを配置しているためNG
<Td>
  <Checkbox />
</Td>
<Td>
  <RadioButton />
</Td>
<Th>
  <Checkbox />
</Th>
```

```jsx
// Td, Thに適切にaria-labelledby, aria-label属性を設定していても置き換え推奨のためNG
<Td>
  <Checkbox aria-labelledby="id1" />
</Td>
<Td>
  <RadioButton aria-labelledby="id2" />
</Td>
<Th>
  <Checkbox aria-label="any text" />
</Th>
```

詳細は eslint-plugin-smarthr の各ルール README を参照してください。

## 使い方チェックリスト

### 使用上の注意 > ユースケースに応じてコンポーネントを使い分ける > 選択肢が複数選択できる場合に使用する
- [must] チェックボックスは選択肢を複数選択できる場合に使う
  - 複数の選択肢から単一選択しかできず、表示領域に余裕がある場合は原則として RadioButton を検討する
  - 選択肢が多い場合や表示領域が狭い場合は MultiCombobox を検討する

### 使用上の注意 > ユースケースに応じてコンポーネントを使い分ける > ビューの切り替えを操作するUIとして使用しない
- [avoid] 即時反映を前提とするビューの切り替えにチェックボックスを使わない
  - チェックボックスは入力後に `送信` や `保存` といった type 属性が `submit` のボタンなどを押すことで入力内容が反映される場合に使う
  - 即時反映を前提とする箇所では TabBar や SegmentedControl、または Switch を使う

### 使用上の注意 > ユースケースに応じてコンポーネントを使い分ける > チェックボックスの並び順
- [should] 横幅に十分なスペースがある場合は基本的に横並びにする
  - 選択肢の文字が長くなる場合は縦並びを検討する

### 使用上の注意 > 2択の切り替えに使う場合の注意
- [should] 「ON/OFF」「有効/無効」「はい/いいえ」といった 2 択の切り替え入力には原則として RadioButton の利用を検討する
  - ブール値で制御できる項目で一方の選択肢が暗黙的になりチェック状態から現在の選択状態が認識しづらい場合は RadioButton を使う
  - ラベルや説明文、ほかの設定項目など前後のコンテキストによりもう一方の選択肢が明示的な場合はチェックボックスを使える（利用規約への同意・削除ダイアログでの注意事項確認など）

### 使用上の注意 > チェックボックス内に操作可能な要素を含めない
- [avoid] チェックボックス内にヘルプページへのリンクやフォームなど、値を選択する以外の操作可能な要素を配置しない
  - チェックボックスの操作に関連するリンクを置きたい場合は Fieldset の `helpMessage` props などを使う

### 状態 > デフォルト
- [should] どの選択肢もチェックされていない状態をデフォルトにする
  - ユーザーの入力作業が向上したりミスを減らせる場合にはデフォルトで選択肢にチェックを入れることを検討する

### 状態 > 混在（mixed）
- [should] 複数のチェックボックスの状態をまとめて示す必要があるチェックボックスで選択状態と未選択状態が混ざっている状態を示す場合は混在選択状態（`mixed=true`）を採用する

### モバイル
- [must] モバイル表示時は画面の幅が狭いため基本的に縦並びにする
  - 誤操作を防ぐために小さい要素間のマージンに従って十分なマージンを確保する