ChillCMS Design System Component

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

Chọn thành viên (Remote Fetch qua API)

Dữ liệu được nạp từ /api/demo/combobox-fetch với debounce 300ms và hiển thị spinner khi đang tải.

Giá trị đã chọn (valueType="object"):

null

Cấu hình `FetchSelectConfig`

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

Chọn sản phẩm (Phân trang 5 sản phẩm/trang)

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.

Sản phẩm đang chọn:

null

Cơ chế Cuộn vô tận (Infinite Scroll)

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ẻ

Quy chuẩn ChillCMS: Không để mất nhãn hiển thị khi nạp ID đơn lẻ từ URL/Database

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.

Thử chuyển ID khởi tạo:

Nhân viên phụ trách (Khởi tạo sẵn giá trị)

ID hiện tại (Value):usr_007

Nhãn hiển thị tương ứng (Label):Đặng Thu Giang (QA Lead)

Cách dùng `fallbackOption`

<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

Thành viên nhóm dự án (Chọn nhiều mục)Ẩn mục đã chọn khỏi popup

Nguyễn Văn AnTrần Thị Bích

Danh sách các mục đã chọn (2):

[
  {
    "label": "Nguyễn Văn An",
    "value": "usr_001"
  },
  {
    "label": "Trần Thị Bích",
    "value": "usr_002"
  }
]

Trải nghiệm Chip Tags & Phím tắt

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 Backspace sẽ 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ắn thẻ chuyên mục (Hỗ trợ tạo thẻ mới tùy ý)

Thiết kế Giao diện UI/UXReact 19 Server Components

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.

Thẻ hiện có:

Thiết kế Giao diện UI/UXReact 19 Server Components

Đặc điểm của `mode="tags"`

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)

Chọn kích thước hiển thị:

Kích thước: xs28px

Kích thước: sm32px

Kích thước: md36px

Kích thước: lg44px

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

Bật trạng thái Lỗi (invalid)Bật trạng thái Vô hiệu hóa (disabled)

Variant: Default

Variant: Filled

Variant: Subtle

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ị

Điều khiển hoàn toàn qua React State (Controlled)

State hiện tại:

null

Sự kiện & Trạng thái Controlled

ArkComboboxFetch hỗ trợ cả hai sự kiện:

onChange(value, selectedValue, details): Trả về giá trị đã được chuyển đổi theo valueType phù 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.

Notifications