Component
Switch
Bật hoặc tắt một cài đặt ngay, không có Save. Một track với thumb trượt đến đầu kia khi bật: viền control trên nền sunken khi tắt, accent khi bật. label đặt tên phía sau switch, và description là dòng thứ hai dưới tên.
Xem trước
import { Switch } from "@/components/ui/switch"
<Switch label="Thông báo qua email" description="Nhận email khi có người nhắc đến bạn." />Cách dùng
Khi nào dùng
- Bật hoặc tắt một cài đặt khi thay đổi có hiệu lực ngay, chẳng hạn thông báo email.
- Một hàng cài đặt trên trang cài đặt, mỗi cài đặt một switch.
Khi nào không dùng
- Lựa chọn chờ Save, hoặc chấp nhận điều khoản. Dùng Checkbox.
- Chọn một trong vài lựa chọn. Dùng RadioGroup.
Biến thể
size
Chiều rộng track lấy từ size-element-*, nên theo cảm ứng; label và description đổi cỡ theo (12, 13, 14px, và 14px ở xl). md cho trang cài đặt và panel prop; sm trong hàng dày và toolbar, chẳng hạn một table; lg và xl cạnh Input và Button cùng size.
import { Switch } from "@/components/ui/switch"
<Switch label="Thông báo qua email" description="Nhận email khi có người nhắc đến bạn." size="sm" />
<Switch label="Thông báo qua email" description="Nhận email khi có người nhắc đến bạn." />
<Switch label="Thông báo qua email" description="Nhận email khi có người nhắc đến bạn." size="lg" />
<Switch label="Thông báo qua email" description="Nhận email khi có người nhắc đến bạn." size="xl" />Ví dụ
Mặc định
import { Switch } from "@/components/ui/switch"
<Switch label="Chế độ tối" />Có description
import { Switch } from "@/components/ui/switch"
<Switch label="Thông báo qua email" description="Nhận email khi có người nhắc đến bạn." defaultChecked />Vô hiệu
import { Switch } from "@/components/ui/switch"
<Switch label="Xác thực hai yếu tố" description="Bắt buộc bởi không gian làm việc của bạn." disabled defaultChecked />Trong một hàng table
sm, cho hàng dày và toolbar. Tên nằm ở cột khác, nên switch dùng aria-label.
import { Switch } from "@/components/ui/switch"
<Switch size="sm" aria-label="Bật webhook triển khai" defaultChecked />Cạnh control lớn
lg khớp Input và Button lg; label và description tăng theo (14px). Phần Variants hiện mọi size cạnh nhau.
import { Input } from "@/components/ui/input"
import { Switch } from "@/components/ui/switch"
<div className="flex w-full max-w-sm flex-col gap-lg">
<Input size="lg" aria-label="Tên không gian làm việc" defaultValue="Acme" />
<Switch size="lg" label="Không gian làm việc công khai" description="Bất kỳ ai có liên kết đều có thể xem." />
</div>Nên và không nên
Nên
- Dùng cho cài đặt có hiệu lực ngay, và áp dụng thay đổi trong onCheckedChange.
- Đặt tên cài đặt trong label, và nói việc bật làm gì trong description.
- Dùng sm trong hàng dày và toolbar, chẳng hạn một table, khi tên nằm ở cột khác (aria-label). Panel prop dùng md, để switch vẫn dễ nhấn trên điện thoại.
- Khớp size của control xung quanh: md với Input md trên trang cài đặt, lg hoặc xl với Input và Button cùng size.
Không nên
- Đừng dùng trong form chờ Save; dùng Checkbox.
- Đừng dùng để chọn một trong vài lựa chọn; dùng RadioGroup.
- Đừng đổi label khi toggle (Bật, Tắt); thumb cho thấy trạng thái.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| size | enum | sm | md | lg | xl | md | Chiều rộng track lấy từ size-element-*, nên theo cảm ứng; label và description đổi cỡ theo (12, 13, 14px, và 14px ở xl). md cho trang cài đặt và panel prop; sm trong hàng dày và toolbar, chẳng hạn một table; lg và xl cạnh Input và Button cùng size. |
| label | node | - | - | Tên nhìn thấy, phía sau switch. Nhấn vào label thì toggle switch. Đặt tên cài đặt, không đặt tên hành động: Thông báo email. |
| description | node | - | - | Dòng thứ hai dưới label: việc bật sẽ 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 | boolean | - | - | Trạng thái controlled. Đi cùng onCheckedChange. |
| defaultChecked | boolean | - | false | Bật ở lần render đầu, khi bạn không control nó. |
| onCheckedChange | function | - | - | Được gọi với true hoặc false khi người dùng toggle. Áp dụng thay đổi ở đây; không có Save. |
| disabled | boolean | - | false | Không focus hoặc toggle được; label cũng mờ đi. |
| required | boolean | - | false | Phải bật để submit form. |
| name | string | - | - | Tên form. Form submit value dưới tên này khi switch đang bật. |
| value | string | - | on | Value được submit khi switch đang bật. |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Track: radius-full, viền control trên nền sunken; khi bật, accent phủ đến mép. Rộng bằng size-element-* và cao bằng một nửa cộng hai viền, nên theo cảm ứng. Chuột: sm 28 x 16px, md 32 x 18px, lg 36 x 20px, xl 44 x 24px; cảm ứng: md 36 x 20px, lg 44 x 24px, xl 48 x 26px. |
| thumb | Thumb: vòng tròn cách mép trong một nửa spacing-xs (2px), chiều cao bên trong trừ spacing-xs: 10px (sm), 12px (md), 14px (lg) hoặc 18px (xl) trên chuột. Lấy màu icon của track: secondary khi tắt, on-accent khi bật. |
| hitArea | ::before trong suốt, căn giữa track, không bao giờ ngắn hơn size-target-min (24px trên chuột, 44px trên cảm ứng). |
| row | Khi có label: hàng chứa switch, rồi Label và description, gap-sm. Dùng chung với Checkbox và RadioGroup. |
| label | Khi có label: một Label sau switch, thẳng hàng với switch ở dòng đầu. 12px ở sm, 14px ở md, lg và xl. |
| description | Khi có description: chữ secondary dưới label, gap-xs, cùng size với label. |
Khả năng truy cập
Role: switch
| Phím | Hành động |
|---|---|
| Space, Enter | Bật hoặc tắt switch. |
| Tab | Chuyển focus tới control tiếp theo; mỗi switch là một tab stop riêng. |
- Đặt tên mọi switch bằng prop label (nhấn vào label thì toggle switch), hoặc aria-label khi tên hiện ở chỗ khác, chẳng hạn một hàng trong table.
- description được nối bằng aria-describedby và được đọc sau tên, ngoài label.
- Thay đổi có hiệu lực ngay. Lựa chọn chờ Save là Checkbox.
- Bật và tắt khác nhau bởi vị trí thumb lẫn nền, nên trạng thái không chỉ dựa vào màu.
- Thumb chỉ trượt khi người dùng cho phép motion; dưới prefers-reduced-motion thì nhảy.
- Trên chuột, track cao 16px (sm), 18px (md), 20px (lg) hoặc 24px (xl), nhưng vùng nhấn không bao giờ nhỏ hơn size-target-min (24px trên chuột, 44px trên cảm ứng). Trên cảm ứng, md, lg và xl lớn theo size-element-md, -lg và -xl; sm giữ nguyên hình và dựa vào vùng nhấn.
- Ở trang phải sang trái, thumb bắt đầu bên phải và trượt sang trái khi bật.
Cài đặt
npx werewolf-ui add switchChạ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 để biết yêu cầu và cách cài qua registry.