Checkbox
Mẫu chuẩnMột lựa chọn bật/tắt độc lập, gửi kèm biểu mẫu khi được chọn.
Playground
Đổi brand, theme và trạng thái. Không có prop size, không có prop variant.
Bấm hộp hoặc bấm nhãn, hoặc dùng Tab + Space để đổi giá trị.
import { Checkbox, Label } from "@nexobox/ui";
<Checkbox id="terms" />
<Label htmlFor="terms">Tôi đồng ý với điều khoản</Label>Khi nào sử dụng
Nên dùng
Một lựa chọn độc lập mà người dùng bật hoặc tắt: đồng ý điều khoản, bật một tuỳ chọn, chọn từng dòng trong danh sách. Nhiều Checkbox cạnh nhau khi các lựa chọn không loại trừ nhau. Dùng indeterminate cho ô cha khi tập con đang chọn một phần.
Tránh dùng
Một giá trị trong nhóm loại trừ nhau — đó là RadioGroup. Bật/tắt một hiệu lực tức thời không cần bấm Lưu — đó là Switch. Một hành động — đó là Button.
Anatomy
| # | Phần | Ghi chú |
|---|---|---|
| 1 | Root | button[role=checkbox] do Radix dựng. 16 px vuông, bo --nf-component-checkbox-radius (4 px). |
| 2 | Indicator | Chỉ render khi data-state là checked hoặc indeterminate. |
| 3 | Glyph | Hugeicons qua Icon của package. Tick02Icon, small. Một glyph duy nhất cho cả hai trạng thái có indicator. |
Nhãn không thuộc primitive. Ghép bằng Label với htmlFor trỏ tới id của Root. Primitive không cung cấp hàng nhãn, không cung cấp khoảng cách nhãn — không có.
Variants & states
Không có variant. Không có size — hộp luôn 16 px, không đổi theo mật độ trang.
Nền field, viền control. Không có indicator.
Nền và viền action-primary, glyph tick.
Cùng glyph tick như checked — khiếm khuyết đã ghi nhận, chưa sửa. Đúng ra cần một glyph gạch ngang riêng.
Di chuột vào hộp. Nền của chính hộp không đổi. Vầng hover là bóng 4px bám đúng bo góc, đọc --nf-component-checkbox-hover.
Giữ chuột xuống. Cùng state layer đọc --nf-component-checkbox-pressed, cộng viền hộp thật đổi sang --nf-component-checkbox-border-pressed. Không co scale — DS-018 rút press-scale khỏi mọi primitive.
Tab tới hộp — ring thật vẽ ở :focus-visible, đọc --nf-component-focus-color / -width / -offset, giống hệt mọi control khác trong kit.
Nền và viền disabled, con trỏ not-allowed. Glyph vẫn dùng màu chữ primary — khiếm khuyết đã ghi nhận, chưa sửa.
Loading, error, empty: không có. Checkbox không bất đồng bộ.
Design tokens
Giá trị theo NexoCrew / light đang chọn trong playground. Root đọc --nf-component-field-background, --nf-semantic-border-control, --nf-semantic-action-primary-background, --nf-semantic-action-primary-border, --nf-component-button-disabled-background, --nf-component-checkbox-radius. Glyph đọc --nf-semantic-action-primary-foreground. State layer (::after) đọc --nf-component-checkbox-hover và --nf-component-checkbox-pressed; viền hộp thật đổi sang --nf-component-checkbox-border-pressed khi nhấn. Density: không có, hộp 16 px không đọc data-nexo-density — nhưng cùng ::after đó nhận vùng chạm 44 px ở @media (pointer: coarse), theo DS-017 clause 6.
API & triển khai
| Prop | Mặc định | Quy ước |
|---|---|---|
| checked | — | Chế độ controlled. boolean | "indeterminate". |
| defaultChecked | false | Chế độ uncontrolled. |
| onCheckedChange | — | Phát khi giá trị đổi. |
| disabled | false | Nêu lý do cạnh control. |
| required | false | Tham gia validation của form. |
| name | — | Tên trường khi submit. |
| value | "on" | Giá trị gửi khi checked. |
CheckboxProps = ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root> — asChild, id, className, style và mọi thuộc tính button gốc đều truyền thẳng xuống Root.