ChillCMS Design System Component

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

Giá trị đang chọn:react
Sử dụng Shorthand cực kỳ nhanh gọn

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)

Chọn kích thước test:

Medium (MD) - Default

Kích thước tiêu chuẩn cho hầu hết form và trang quản trị

Chiều cao: 36pxPadding: 14px
Kiểm tra alignment ngang hàng: Input + Combobox + Button
So sánh trực quan cả 4 kích cỡ (XS, SM, MD, LG)
Size: xs
Size: sm
Size: md
Size: lg

3. Biến thể giao diện (Variants)

Hỗ trợ 3 phong cách nền và viền: default, filled và subtle

Default

Viền rõ, nền bề mặt chuẩn, shadow nhẹ

Filled

Nền surface-subtle xám nhẹ, viền tinh tế, tập trung form dài

Subtle

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

Chọn nhiều Framework (Multiple = true)
ReactNext.js
Dữ liệu state bên ngoài (Tags preview):
ReactNext.js

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

Live Inspector
Trạng thái Popup: CLOSED
Giá trị đã chọn: ["jp"]
Nội dung ô nhập: "Nhật Bản"
Lịch sử sự kiện gần nhất:
Chưa có tương tác nào...

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)

Bình thường + Helper text

Thông tin này sẽ in trên hóa đơn VAT

Báo lỗi Validation (Invalid)

Vui lòng chọn quốc gia cư trú hợp lệ

Vô hiệu hóa (Disabled)

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...)

Trạng thái chọn hiện tại:API Calls: 0
Mã ID (Scalar Value):usr_007
Từ khóa gõ (Query):""
Chi tiết đối tượng đã chọn:
Đặng Thu Giang
Kiểm thử QA • Kỹ thuật (giang.dang@chillcms.dev)
Hướng dẫn kỹ thuật: Async Search Chọn 1 mục

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

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

Gõ từ khóa để nạp kết quả; ấn Enter để chọn; ấn Backspace hoặc click (X) để gỡ

Danh sách đã chọn (2):API Calls: 0
Nguyễn Văn An(usr_001)Trần Thị Bích(usr_002)
Mảng giá trị ID (IDs array):
["usr_001","usr_002"]
Hướng dẫn kỹ thuật: Async Search Chọn nhiều mục

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 />}
/>
Phân biệt khi nào nên dùng ArkCombobox vs. ArkComboboxFetch

- 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ínhKiểu dữ liệuMặc địnhMô tả
itemsreadonly T[]undefinedMảng danh sách các mục. Component tự động lọc substring khi gõ.
collectionListCollection<T>undefinedBộ 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.
clearablebooleanfalseHiển thị nút (X) để xóa nhanh nội dung khi có giá trị.
showTriggerbooleantrueHiển thị icon mũi tên chevron ở cuối ô input để mở dropdown.
startIconReactNodeundefinedIcon 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.
multiplebooleanfalseCho phép chọn nhiều giá trị trong danh sách.
invalidbooleanfalseKích hoạt viền đỏ cảnh báo và hiệu ứng focus đỏ.
© 2026. FlatVn All rights reserved. Version 4.4.2