Ark Combobox Fetch
Thành phần hộp chọn tìm kiếm bất đồng bộ (Remote Select) kết hợp @ark-ui/react/combobox, useFetchSelect, và Tailwind CSS v4. Tự động hỗ trợ debounce tìm kiếm từ xa, cuộn vô tận nạp thêm trang, chế độ gắn thẻ mới (tags mode), và quy chuẩn fallbackOption chống mất nhãn hiển thị.
1. Tìm kiếm từ xa cơ bản (Basic Remote Fetch)Phổ biến nhất
Nạp dữ liệu qua API với cơ chế debounce tự động và loading spinner
Dữ liệu được nạp từ /api/demo/combobox-fetch với debounce 300ms và hiển thị spinner khi đang tải.
null
Chỉ cần cung cấp object config gồm URL endpoint và cặp trường field: { id, label }.
<ArkComboboxFetch
config={{
axios: {
url: '/api/demo/combobox-fetch',
_data: 'routes/api.demo.combobox-fetch/route',
params: { type: 'users' },
},
field: { id: 'id', label: 'name' },
debounceMs: 300,
}}
value={selectedUser}
onChange={(val) => setSelectedUser(val)}
placeholder="Tìm nhân sự..."
clearable
/>2. Cuộn vô tận & Phân trang (Infinite Scroll)Tối ưu hiệu năng
Tự động tải thêm trang khi người dùng cuộn đến cuối danh sách popup
Cuộn xuống dưới cùng của menu thả xuống để kích hoạt nạp trang kế tiếp (page 1, 2, 3...) kèm thông báo tải thêm.
null
Sử dụng mapOption để định dạng thêm description chứa SKU và đơn giá. Khi cuộn tới đáy popup, hook useFetchSelect sẽ kiểm tra hasMore và tự động gọi trang tiếp theo.
const config = {
axios: {
url: '/api/demo/combobox-fetch',
_data: 'routes/api.demo.combobox-fetch/route',
limit: 5,
params: { type: 'products' },
},
mapOption: (item) => ({
label: item.name,
value: item.id,
description: `${item.sku} • ${item.price}`,
}),
};3. Quy chuẩn Fallback Option (Preloaded Initial Value)Quy chuẩn bắt buộc
Bảo đảm hiển thị đúng tên khi nạp dữ liệu ban đầu từ database/URL chỉ có ID đơn lẻ
Khi trang vừa tải, combobox nhận giá trị là một scalar ID đơn (ví dụ usr_007). Nếu không có fallbackOption, người dùng sẽ thấy ô input trống hoặc hiển thị chuỗi mã thô cho đến khi danh sách remote fetch về đủ. Cung cấp fallbackOption đảm bảo nhãn thân thiện được hiển thị ngay lập tức 100% thời gian.
<ArkComboboxFetch
config={userFetchConfig}
value={loaderData.assignedUserId} // "usr_007"
valueType="string"
fallbackOption={loaderData.assignedUserOption}
// { label: "Đặng Thu Giang (QA Lead)", value: "usr_007" }
onChange={(id) => setUserId(id)}
/>4. Chọn nhiều mục với Chips (Multiple Mode)
Hiển thị danh sách thẻ chip với nút xóa nhanh và hỗ trợ phím Backspace
[
{
"label": "Nguyễn Văn An",
"value": "usr_001"
},
{
"label": "Trần Thị Bích",
"value": "usr_002"
}
]- Mỗi mục đã chọn được hiển thị dưới dạng badge chip có nút
(X)để gỡ nhanh. - Khi con trỏ ở ô nhập và nội dung tìm kiếm rỗng, bấm phím
Backspacesẽ tự động xóa chip liền trước đó. - Khi truyền
hideSelectedOptions={true}, các mục đã chọn sẽ tự động được lọc bỏ khỏi menu gợi ý.
<ArkComboboxFetch
mode="multiple"
config={usersConfig}
value={selectedUsers}
hideSelectedOptions={true}
onChange={(val) => setSelectedUsers(val)}
clearable
/>5. Chế độ gắn thẻ & Tạo mục mới (Tags Creation Mode)Linh hoạt
Cho phép người dùng gõ từ khóa tự do để tạo mục mới tức thì khi không tìm thấy trong API
Gõ một từ khóa không có trong danh mục (ví dụ: "AI Agentic Coding") rồi click vào mục Mới: [từ khóa] để tạo tag mới.
Chế độ mode="tags" kế thừa khả năng chọn nhiều mục của multiple, đồng thời tự động kiểm tra từ khóa người dùng nhập vào. Nếu từ khóa chưa tồn tại trong danh sách nạp từ API, một tùy chọn mới với cờ created: true và tiền tố Mới: sẽ xuất hiện ở đầu menu gợi ý.
<ArkComboboxFetch
mode="tags"
config={categoriesConfig}
value={tags}
onChange={(val) => setTags(val)}
placeholder="Chọn hoặc tạo thẻ mới..."
/>6. Ma trận kích thước (Size Matrix)
Đồng bộ chính xác với hệ thống kích thước Input và Button (xs: 28px, sm: 32px, md: 36px, lg: 44px)
7. Biến thể giao diện & Trạng thái lỗi (Variants & States)
3 biến thể giao diện: default, filled, subtle cùng trạng thái invalid và disabled
8. Điều khiển trạng thái (Controlled State)
Đồng bộ mượt mà với state React và thao tác lập trình giá trị
null
ArkComboboxFetch hỗ trợ cả hai sự kiện:
onChange(value, selectedValue, details): Trả về giá trị đã được chuyển đổi theovalueTypephù hợp nộp form.onValueChange(selectedValue, details): Trả về trực tiếp object option đầy đủ.
9. Bảng tra cứu thuộc tính (Props Reference)
| Thuộc tính | Kiểu dữ liệu | Mặc định | Mô tả |
|---|---|---|---|
| config | FetchSelectConfig | Bắt buộc | Cấu hình axios URL, _data, params, field mapper và debounceMs. |
| fallbackOption | FetchSelectOption | undefined | Option dự phòng giữ nguyên nhãn hiển thị trước khi remote API tải xong. |
| mode | 'multiple' | 'tags' | undefined | Chế độ chọn nhiều mục hoặc cho phép nhập tạo thẻ mới. |
| valueType | 'object' | 'string' | 'number' | 'raw' | 'object' | Định dạng kiểu dữ liệu trả về trong sự kiện onChange. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Kích thước chuẩn 4 mức đồng bộ với Input và Button. |
| variant | 'default' | 'filled' | 'subtle' | 'default' | Phong cách viền và nền của khung nhập. |
| clearable | boolean | true | Hiển thị nút (X) xóa nhanh lựa chọn khi đã có giá trị. |
| hideSelectedOptions | boolean | false | Ẩn các mục đã chọn khỏi danh sách gợi ý khi ở multiple mode. |
| invalid | boolean | false | Trạng thái cảnh báo lỗi với viền đỏ và hiệu ứng focus đỏ. |
| disabled | boolean | false | Vô hiệu hóa toàn bộ tương tác của ô chọn. |
| onChange | ArkComboboxFetchChangeHandler | undefined | Callback kích hoạt khi giá trị thay đổi, nhận value đã được cast theo valueType. |