Switch
Mẫu chuẩnBật một hiệu lực có tác dụng ngay khi người dùng chạm vào công tắc, không chờ một nút Lưu nào khác.
Playground
Đổi brand, theme và trạng thái. Không có prop size, không có prop variant.
Đang tắt.
import { Switch, Label } from "@nexobox/ui";
<Switch id="notify" />
<Label htmlFor="notify">Nhận thông báo</Label>Khi nào sử dụng
Nên dùng
Bật hoặc tắt một hiệu lực có tác dụng ngay khi chạm vào: bật thông báo, bật chế độ tối, mở một tính năng đang chạy nền.
Tránh dùng
Một giá trị chờ nút Lưu trong một form — đó là Checkbox. Một hành động tức thời không có trạng thái bền vững — đó là Button.
Switch mô tả một hiệu lực đang chạy và có hiệu lực ngay khi bật. Checkbox mô tả một giá trị sẽ được gửi khi người dùng bấm Lưu. Nếu màn hình có nút Lưu ở cuối và giá trị chỉ có tác dụng sau khi bấm nút đó, dùng Checkbox — dùng Switch ở đó sẽ nói dối người dùng rằng thay đổi đã có hiệu lực.
Anatomy
| # | Phần | Ghi chú |
|---|---|---|
| 1 | Root | button[role=switch] do Radix dựng. Track 40×20 px, bo --nf-foundation-radius-pill. |
| 2 | Thumb | Hình tròn 16 px, luôn hiển thị, trượt ngang trong track. |
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 — track luôn 40×20 px, không đổi theo mật độ trang. Không có indeterminate — khác Checkbox, Switch chỉ có hai giá trị.
Track nền --nf-semantic-border-control.
Track nền --nf-semantic-action-primary-background.
Di chuột vào track. Nền track không đổi. Vầng hover là bóng 4px bám đúng hình viên thuốc, đọc --nf-component-switch-hover.
Giữ chuột xuống. Cùng state layer đọc --nf-component-switch-pressed. Không co scale — DS-018 rút press-scale khỏi mọi primitive.
Outline theo --nf-component-focus-*, offset riêng. Ảnh mô phỏng bằng class xem trước, không phải Tab thật.
Track nền --nf-component-button-disabled-background, con trỏ not-allowed.
Loading, error, empty: không có. Switch không bất đồng bộ.
Design tokens
Giá trị theo NexoCrew / light đang chọn trong playground. Track đọc --nf-semantic-border-control khi tắt và --nf-semantic-action-primary-background khi bật; thumb luôn đọc --nf-component-field-background. Disabled đọc --nf-component-button-disabled-background. State layer (::after, sau thumb) đọc --nf-component-switch-hover và --nf-component-switch-pressed. Density: không có, track 20 px không đọc data-nexo-density — nhưng cùng ::after đó nhận vùng chạm 44 px ở @media (pointer: coarse).
API & triển khai
| Prop | Mặc định | Quy ước |
|---|---|---|
| checked | — | Chế độ controlled. |
| 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. |
SwitchProps = ComponentPropsWithoutRef<typeof SwitchPrimitive.Root> — asChild, id, className, style và mọi thuộc tính button gốc đều truyền thẳng xuống Root.