# Checkbox

Ô 16px bật hoặc tắt một lựa chọn, hoặc cho thấy một nhóm đang bật một phần. Lõm với viền control khi tắt; accent với dấu check khi bật, hoặc dấu trừ khi bật một phần. label đặt tên sau ô, và description là dòng thứ hai dưới tên.

**Phụ thuộc:** npm: 2 trực tiếp, 4 tổng; registry: 3 trực tiếp, 4 tổng.

## Cách dùng

### Khi nào dùng

- Bật hoặc tắt một lựa chọn khi thay đổi có hiệu lực lúc lưu, chẳng hạn chấp nhận điều khoản.
- Chọn số mục bất kỳ từ một danh sách, chẳng hạn các hàng trong bảng, mỗi hàng một ô riêng.

### Khi nào không dùng

- Cài đặt áp dụng ngay, chẳng hạn chế độ tối. Dùng Switch.
- Chọn đúng một trong vài lựa chọn. Dùng RadioGroup, hoặc Select cho danh sách dài.
- Chạy một hành động, chẳng hạn xóa các hàng đã chọn. Dùng Button.

## Biến thể

### checked

Trạng thái được kiểm soát: true, false hoặc "indeterminate" (bật một phần). Ghép với onCheckedChange.

Giá trị: `false`, `true`, `indeterminate`. Mặc định: `false`.

## Ví dụ

### Mặc định

```tsx
<Checkbox label="Gửi email cho tôi về cập nhật sản phẩm" />
```

### Có description

description được đọc sau tên.

```tsx
<Checkbox label="Bản tin hàng tuần" description="Bản tóm tắt hoạt động của nhóm bạn, mỗi Thứ Hai." defaultChecked />
```

### Bắt buộc

Không gửi được form cho đến khi ô bật. Ghi chú Required nằm trên label; required trên ô là thứ trình đọc màn hình thông báo.

```tsx
<Checkbox label="Tôi chấp nhận điều khoản" required requiredText="Bắt buộc" />
```

### Bật một phần

Ô chọn mọi hàng, trong khi chỉ một số hàng được chọn. Bảng hiện tên, nên ô dùng aria-label.

```tsx
<Checkbox defaultChecked="indeterminate" aria-label="Chọn tất cả hàng" />
```

### Vô hiệu

```tsx
<Checkbox label="Đăng nhập bằng SSO" description="Quản trị viên của bạn đã bật mục này cho mọi người." disabled defaultChecked />
```

## Nên và không nên

### Nên

- Đặt tên bằng prop label; thêm description khi chỉ tên không nói rõ việc bật nó làm gì.
- Dùng nó cho lựa chọn có hiệu lực khi form được lưu, hoặc để chọn nhiều mục.
- Dùng bật một phần cho ô chọn một danh sách mà chỉ một số mục đang bật.

### Không nên

- Đừng dùng nó cho cài đặt áp dụng ngay; dùng Switch.
- Đừng dùng nó để chọn đúng một trong vài lựa chọn; dùng RadioGroup.
- Đừng đặt tên trước ô, hoặc đặt description bên trong label.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `label` | `node` |  |  | Tên nhìn thấy, sau ô. Nhấn vào đó thì bật tắt ô. Ngắn, viết hoa chữ cái đầu câu: Email me product updates. |
| `description` | `node` |  |  | Dòng thứ hai dưới label: việc bật nó làm gì. Cần label. |
| `requiredText` | `node` |  | `Required` | Ghi chú Required hiện khi có required và label, cho trang bằng ngôn ngữ khác. |
| `checked` | `enum` | `false`, `true`, `indeterminate` | `false` | Trạng thái được kiểm soát: true, false hoặc "indeterminate" (bật một phần). Ghép với onCheckedChange. |
| `defaultChecked` | `boolean` |  | `false` | Bật ở lần render đầu, khi bạn không kiểm soát nó. Cũng nhận "indeterminate". |
| `onCheckedChange` | `function` |  |  | Được gọi với true hoặc false khi người dùng bật tắt ô. |
| `disabled` | `boolean` |  | `false` | Không focus hoặc bật tắt được. Cũng vô hiệu Label của nó. |
| `required` | `boolean` |  | `false` | Phải bật thì mới gửi được form, chẳng hạn chấp nhận điều khoản. Cũng đánh dấu Label của nó là required. |
| `name` | `string` |  |  | Tên trong form. Form gửi value dưới tên này khi ô đang bật. |
| `value` | `string` |  | `on` | Giá trị được gửi khi ô đang bật. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Ô: 16px, radius-inner, viền control trên nền lõm. Khi bật và khi bật một phần, accent tô đến mép. |
| `icon` | Dấu check (bật) hoặc dấu trừ (bật một phần): Tabler, 16px, màu icon on-accent. |
| `hitArea` | ::before trong suốt, căn giữa trên ô, không bao giờ nhỏ hơn size-target-min (24px với chuột, 44px với cảm ứng). |
| `label` | Khi có label: một Label sau ô, ngang hàng với ô ở dòng đầu. Nó theo required và disabled. |
| `description` | Khi có description: chữ phụ 14px dưới label, gap-xs. |
| `row` | Khi có label: hàng chứa ô, rồi Label và description, gap-sm. RadioGroup và Switch dùng chung hàng này. |

## Khả năng truy cập

Role: `checkbox`

| Phím | Hành động |
| --- | --- |
| `Space` | Bật hoặc tắt ô. Ô đang bật một phần thì chuyển sang bật. |
| `Tab` | Chuyển focus tới ô tiếp theo; mỗi checkbox là một tab stop riêng. |

- Đặt tên cho mọi ô: prop label (nhấn vào đó thì bật tắt ô), hoặc aria-label khi tên hiện ở nơi khác, chẳng hạn một hàng trong bảng. Một Label riêng với htmlFor cũng được khi bố cục cần.
- description được nối bằng aria-describedby và nằm ngoài phần tử label, nên trình đọc màn hình đọc nó sau tên thay vì như một phần của tên.
- Bật một phần là aria-checked="mixed", cho ô chọn một danh sách mà chỉ một số mục đang bật.
- Enter không bật tắt checkbox, giống checkbox native: nó gửi form.
- Ô là 16px nhưng vùng nhấn là size-target-min (24px với chuột, 44px với cảm ứng).
- Trong form, một input ẩn mang name và value, nên form gửi nó như checkbox native.
- Bật và tắt khác nhau bằng dấu check hoặc dấu trừ, và cả phần tô, nên trạng thái không chỉ dựa vào màu.

## Cài đặt

```bash
npx werewolf-ui add checkbox
```

Chạy `npx werewolf-ui init` một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem [Cài đặt](https://www.werewolf-ui.dev/vi/docs/installation.md) để biết yêu cầu và cách cài qua registry.