Combobox

Combobox kết hợp ô nhập và listbox: gõ để lọc rồi chọn một hoặc nhiều lựa chọn.

Lọc không phân biệt dấu tiếng Việt (gõ “da nang” vẫn ra “Đà Nẵng”). Bàn phím: mũi tên để duyệt, Enter để chọn, Esc để đóng. multiselect hiện ô tick cho từng option; freeform cho phép giữ giá trị tự gõ không có trong danh sách.

Thành phố

Import

Cài từ npm, chép mã nguồn vào dự án bằng @yugen-ui/cli hoặc shadcn CLI, hoặc import thẳng khi làm việc trong repo này.

TSX

// npm install yugen-uiimport { Combobox } from "yugen-ui";

Biến thể

Mỗi ô là một mẫu độc lập: hover để Copy, hoặc bấm Code để xem mã nguồn.

Chọn nhiều

multiselect: listbox giữ mở sau mỗi lần chọn, ô hiện danh sách đã chọn.

Nhóm & option disabled

Option có group được gom dưới tiêu đề.

Giá trị: (trống)

Freeform (controlled)

Gõ giá trị không có trong danh sách rồi Enter hoặc rời ô để giữ lại.

Appearance, kích thước & disabled

Cùng bộ appearance / size với Input.

Cách dùng

Nên

Dùng khi danh sách dài (hơn ~10 mục) và người dùng biết mình cần tìm gì.
Viết placeholder gợi ý rằng có thể gõ để tìm.
Bật freeform khi giá trị hợp lệ không giới hạn trong danh sách.

Không nên

Không dùng cho vài lựa chọn ngắn — dùng Dropdown hoặc RadioGroup.
Không dùng multiselect khi các giá trị cần hiển thị rõ từng mục — dùng TagPicker.

Props

Prop · Kiểu	Mặc định	Mô tả
options(string \| { value, label?, disabled?, group? })[]	Mặc định: —	Danh sách lựa chọn.
value / defaultValuestring \| string[]	Mặc định: —	string khi chọn một; string[] khi multiselect.
onValueChange(value: string \| string[]) => void	Mặc định: —	Callback khi chọn.
multiselectboolean	Mặc định: false	Cho phép chọn nhiều (option có ô tick).
freeformboolean	Mặc định: false	Giữ văn bản tự gõ làm giá trị.
noResultsTextReactNode	Mặc định: "No results found"	Hiện khi lọc không ra option nào.
appearance"outline" \| "underline" \| "filled-darker" \| "filled-lighter"	Mặc định: "outline"	Kiểu ô.
size"small" \| "medium" \| "large"	Mặc định: "medium"	Chiều cao 24 / 32 / 40px.
className / listboxClassNamestring	Mặc định: —	Class cho ô / bề mặt listbox.

Messages

Chữ có sẵn của component: nhãn, aria-label, thông báo cho trình đọc màn hình.

Mặc định là tiếng Anh. Đổi qua prop messages của YugenProvider, theo namespace bên dưới; messagesVi chứa bản tiếng Việt. Xem Ngôn ngữ giao diện.

messages.combobox

Khoá · Kiểu	Mặc định (tiếng Anh)	messagesVi
noResultsstring Nội dung khi không có kết quả lọc.	Mặc định (tiếng Anh)`"No results found"`	messagesVi`"Không tìm thấy kết quả"`
useFreeform(query: string) => string Gợi ý khi `freeform` và chữ gõ không khớp option nào.	Mặc định (tiếng Anh)(query) => `Press Enter to use “${query}”`	messagesVi(query) => `Nhấn Enter để dùng “${query}”`
closeListstring aria-label nút mũi tên khi listbox đang mở.	Mặc định (tiếng Anh)`"Close list"`	messagesVi`"Đóng danh sách"`
openListstring aria-label nút mũi tên khi listbox đang đóng.	Mặc định (tiếng Anh)`"Open list"`	messagesVi`"Mở danh sách"`
listLabelstring Tên của listbox khi ô nhập không có nhãn hiển thị (Field nối nhãn qua aria-labelledby).	Mặc định (tiếng Anh)`"Suggestions"`	messagesVi`"Gợi ý"`