ArkToggle Component
Nút bật/tắt đơn lẻ (toggle button) được xây dựng trên nền tảng @ark-ui/react/toggle và hệ thống thiết kế Tailwind CSS v4. Hỗ trợ 4 kích thước (xs/sm/md/lg) đồng bộ với Input & Button, 4 biến thể giao diện, chế độ icon-only và Compound Anatomy.
1. Cơ bản: Shorthand API
ShorthandSử dụng <ArkToggle> với icon, children và defaultPressed. Click để bật/tắt.
2. Bộ sưu tập 4 Biến thể Giao diện
Chuyển đổi giữa các kiểu dáng: default, outline, subtle, ghost.
3. Kích thước (xs / sm / md / lg)
Size SyncĐồng bộ kích thước với Input và Button thông qua hệ thống --control-height tokens.
4. Đồng bộ kích thước với Input và Button (Input & Button Sync)
Pixel PerfectTrực quan hoá sự đồng nhất tuyệt đối về chiều cao và kích thước icon giữa Input, ArkToggle (có text & icon-only) và Button ở cả 4 kích thước: xs, sm, md, lg.
5. Trạng thái Controlled & onPressedChange
ControlledQuản lý trạng thái bật/tắt bằng state bên ngoài. Nhận callback khi thay đổi.
6. Toggle Indicator (Nội dung thay đổi theo trạng thái)
CompoundSử dụng <ArkToggle.Indicator> để render nội dung khác nhau khi bật/tắt.
7. Thanh công cụ Icon-Only
ToolbarKết hợp nhiều toggle icon-only tạo thành thanh định dạng văn bản.
8. Trạng thái Disabled
Toggle bị vô hiệu hoá. Không thể click, opacity giảm, cursor thay đổi.
9. Ví dụ thực tế: Thẻ Bài viết
Real-worldSử dụng ArkToggle trong ngữ cảnh thực tế – ghim bài viết, yêu thích và đánh dấu.
Hướng dẫn tích hợp Ark UI với Tailwind CSS v4
Bài viết chi tiết về cách xây dựng các thành phần giao diện headless kết hợp hệ thống design token nhất quán. Bao gồm ToggleGroup, Toggle, Tabs và nhiều thành phần khác.
10. Bảng thuộc tính API của ArkToggle
Danh sách các props chính để cấu hình thành phần ArkToggle.
| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
|---|---|---|---|
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Kích thước đồng bộ với Input & Button (--control-height tokens). |
| variant | 'default' | 'outline' | 'subtle' | 'ghost' | 'default' | Phong cách giao diện khi bật/tắt. |
| icon | ReactNode | undefined | Icon hiển thị trước nội dung, tự động co theo --control-icon-size. |
| iconOnly | boolean | false | Render nút vuông (chiều rộng = chiều cao), bỏ padding ngang. |
| pressed / defaultPressed | boolean | undefined | Trạng thái bật/tắt (Controlled / Uncontrolled). |
| onPressedChange | (details: { pressed: boolean }) => void | undefined | Callback khi trạng thái bật/tắt thay đổi. |
| disabled | boolean | false | Vô hiệu hoá toggle, ngăn click và giảm opacity. |