Ark Combobox
Thành phần hộp chọn tìm kiếm kết hợp sức mạnh accessibility chuẩn WAI-ARIA của @ark-ui/react/combobox với hệ thống token kiểu dáng hiện đại của Tailwind CSS v4. Đồng bộ chuẩn 4 kích thước điều khiển (xs, sm, md, lg) ngang hàng với Input và Button.
1. Ví dụ cơ bản (Basic Combobox)Phổ biến nhất
Sử dụng cú pháp Shorthand nhanh chóng với khả năng lọc tự động
Tự động lọc theo tên hoặc mô tả framework
Chỉ cần truyền mảng items, component sẽ tự động tính toán bộ sưu tập lọc case-insensitive, hiển thị gợi ý, nút xóa và nút toggle mũi tên.
<ArkCombobox
label="Chọn Framework"
items={frameworks}
value={val}
onValueChange={(e) => setVal(e.value)}
placeholder="Gõ để tìm kiếm..."
clearable
/>2. Ma trận kích thước (Size Matrix & Alignment)Token đồng bộ
Đồng bộ chính xác với hệ thống kích thước của Input và Button (xs: 28px, sm: 32px, md: 36px, lg: 44px)
Medium (MD) - Default
Kích thước tiêu chuẩn cho hầu hết form và trang quản trị
3. Biến thể giao diện (Variants)
Hỗ trợ 3 phong cách nền và viền: default, filled và subtle
Viền rõ, nền bề mặt chuẩn, shadow nhẹ
Nền surface-subtle xám nhẹ, viền tinh tế, tập trung form dài
Viền mờ thanh mảnh, phù hợp thanh tìm kiếm header
4. Nút xóa nhanh & Start Icon
Tích hợp nút (X) để xóa giá trị ngay lập tức và icon tiền tố tùy biến
Có Start Icon & Nút Xóa (Clearable)
Khi nhập text hoặc chọn item, nút (X) xuất hiện. Bấm (X) sẽ xóa nhanh giá trị mà không làm mất focus.
Tùy biến Icon Tìm Kiếm theo ngữ cảnh
Start icon tự động tính toán bù trừ padding trái theo token --control-adornment-offset.
5. Tùy biến nội dung mục hiển thị
Hiển thị icon, tiêu đề phụ, badge định dạng và trạng thái item
6. Phân nhóm danh mục (Grouped Items)
Sử dụng ItemGroup và ItemGroupLabel để tổ chức danh sách có cấu trúc
7. Chọn nhiều mục cùng lúc (Multiple Selection)
Cho phép chọn nhiều giá trị và hiển thị danh sách nhãn đã chọn
Hỗ trợ phím Space / Enter để chọn nhiều mục liên tục mà không đóng popup nhờ cấu hình closeOnSelect= (mặc định trong chế độ multiple).
8. Tự động highlight & Gợi ý điền trước
Cấu hình inputBehavior='autohighlight' hoặc 'autocomplete' tăng tốc độ gõ
inputBehavior="autohighlight"
Tự động highlight mục kết quả khớp đầu tiên khi bạn gõ, chỉ cần ấn Enter để chọn ngay.
inputBehavior="autocomplete"
Dùng phím mũi tên lên/xuống sẽ tự động điền giá trị gợi ý trực tiếp vào ô input.
9. Kiểm soát trạng thái & Theo dõi sự kiện (Controlled State)
Bảng live inspector theo dõi giá trị inputValue, selected value và trạng thái mở popup
10. Trạng thái Form & Validation
Các chế độ thông báo lỗi (invalid), hướng dẫn (helperText), vô hiệu hóa (disabled)
Thông tin này sẽ in trên hóa đơn VAT
Vui lòng chọn quốc gia cư trú hợp lệ
Khu vực này hiện đang khóa bảo trì
11. Cấu trúc Compound API nâng cao
Tự do sắp đặt từng bộ phận Control, Trigger, Content, Positioner theo ý muốn
12. Tìm kiếm bất đồng bộ - Chọn 1 mục (Single Async Search)Chọn 1 mục
Gọi dữ liệu API bất đồng bộ với cơ chế debounce, spinner xoay mượt và bảo toàn nhãn hiển thị
Gõ từ khóa để gọi API (ví dụ: An, Giang, Phúc, Kỹ thuật, Bảo mật...)
1. Debounce 300ms: Sử dụng setTimeout và AbortController để hủy bỏ request cũ khi người dùng gõ liên tục, tiết kiệm băng thông máy chủ.
2. filterFn={() => true}: Vì kết quả đã được lọc chính xác từ phía máy chủ theo nhiều trường (tên, email, phòng ban), truyền filterFn={() => true} để ngăn ArkCombobox lọc chuỗi substring lần thứ hai ở client.
3. Bảo toàn nhãn qua Object Value: Truyền value={selectedOption ? { label, value } : null} giúp ô nhập hiển thị đúng nhãn ngay cả khi danh sách results cập nhật.
<ArkCombobox
items={results}
filterFn={() => true}
value={selectedOption ? { label: selectedOption.label, value: selectedOption.value } : null}
onChange={(_val, opt) => setSelectedOption(opt)}
onInputValueChange={(e) => {
if (e.reason === 'input-change') executeSearch(e.inputValue);
}}
clearable
startIcon={loading ? <Loader2 className="animate-spin text-primary" /> : <Search />}
/>13. Tìm kiếm bất đồng bộ - Chọn nhiều mục (Multiple Async Search)Chọn nhiều mục
Chọn nhiều mục qua API từ xa với thẻ Chip tags, gỡ phím Backspace, tùy chọn ẩn mục đã chọn và bảo toàn danh sách chọn
Gõ từ khóa để nạp kết quả; ấn Enter để chọn; ấn Backspace hoặc click (X) để gỡ
["usr_001","usr_002"]
1. Bảo toàn thẻ Chip (Chip Retention): Khi người dùng gõ từ khóa mới, kết quả API chỉ trả về các mục khớp từ khóa mới. Cơ chế bộ nhớ đệm selectedOptionCache của ArkCombobox tự động giữ lại các mục đã chọn trong danh sách items nội bộ, giúp các thẻ chip không bị biến mất khi từ khóa thay đổi.
2. hideSelectedOptions={true}: Tự động loại trừ các mục đã được chọn ra khỏi menu popup gợi ý, giúp người dùng không bị click nhầm chọn trùng.
3. Phím tắt bàn phím: Hỗ trợ phím Enter để chọn mục, và phím Backspace khi ô nhập trống để gỡ nhanh chip cuối cùng.
<ArkCombobox
multiple
items={results}
filterFn={() => true}
value={selectedUsers}
hideSelectedOptions={true}
onChange={(_val, opts) => setSelectedUsers(opts)}
onInputValueChange={(e) => {
if (e.reason === 'input-change') executeSearch(e.inputValue);
}}
clearable
startIcon={loading ? <Loader2 className="animate-spin text-primary" /> : <Search />}
/>- Sử dụng ArkCombobox (Async Search) khi bạn muốn toàn quyền kiểm soát cách gọi API, logic debounce thủ công, tích hợp dữ liệu từ React Query / SWR / WebSocket, hoặc danh sách dữ liệu có giới hạn.
- Sử dụng ArkComboboxFetch khi bạn cần giải pháp trọn gói bao gồm cấu hình Axios tự động, phân trang cuộn vô tận (Infinite Scroll), chế độ tự do tạo thẻ mới (mode="tags"), và cơ chế fallbackOption chống mất nhãn khi nạp dữ liệu ban đầu từ database/URL chỉ có scalar ID đơn.
Bảng thông số kỹ thuật (API Specs)
Tổng hợp thuộc tính cốt lõi của thành phần ArkCombobox
| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
|---|---|---|---|
| items | readonly T[] | undefined | Mảng danh sách các mục. Component tự động lọc substring khi gõ. |
| collection | ListCollection<T> | undefined | Bộ sưu tập tạo từ createListCollection hoặc useListCollection. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Kích thước điều khiển, tương thích hệ thống token control-size. |
| variant | 'default' | 'filled' | 'subtle' | 'default' | Biến thể phong cách viền và nền. |
| clearable | boolean | false | Hiển thị nút (X) để xóa nhanh nội dung khi có giá trị. |
| showTrigger | boolean | true | Hiển thị icon mũi tên chevron ở cuối ô input để mở dropdown. |
| startIcon | ReactNode | undefined | Icon tiền tố đặt ở đầu ô nhập với padding bù trừ tự động. |
| inputBehavior | 'none' | 'autohighlight' | 'autocomplete' | 'none' | Hành vi tự động highlight hoặc tự động điền gợi ý khi gõ phím. |
| multiple | boolean | false | Cho phép chọn nhiều giá trị trong danh sách. |
| invalid | boolean | false | Kích hoạt viền đỏ cảnh báo và hiệu ứng focus đỏ. |