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

Chọn Framework (Shorthand API)

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

Hệ sinh thái công nghệ (Custom Badges & Subtitle)

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

Phân loại kỹ năng theo nhóm

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

Tương tác có kiểm soát (Controlled state)

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

Tài khoản thanh toán

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

Báo lỗi Validation (Invalid)

Quốc gia cư trú *

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

Vô hiệu hóa (Disabled)

Khu vực máy chủ

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

Gói dịch vụ hỗ trợ kỹ thuật (Compound API Layout)

12. Tìm kiếm bất đồng bộ (Async / Remote Search)

Mô phỏng gọi API từ máy chủ với trạng thái spinner xoay mượt mà

Mô phỏng tìm kiếm dữ liệu từ xa (Remote / Dynamic API)

Nhập ít nhất 1 ký tự để tìm kiếm

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 đỏ.

Notifications