ComponentPicker & Select
Combobox
Combobox thuộc nhóm Picker & Select. Xem demo trực tiếp, cách tích hợp và các lưu ý triển khai.
Bắt đầu nhanh
Import Combobox từ entry của gói Free. Các ví dụ bên dưới thể hiện những kiểu tương tác và cấu hình được hỗ trợ.
component.tsxtsx
import { Combobox } from '@underverse-ui/underverse';Ví dụ tương tác
Dùng thử Combobox thật, xem mã ví dụ và tra cứu các prop đã được mô tả.
Đang tải ví dụ tương tác…
Tham chiếu
Tham chiếu API
Tra cứu các thuộc tính, kiểu dữ liệu được chấp nhận, giá trị mặc định và lưu ý về hành vi.
Dữ liệu được sinh từ API TypeScript công khai của thư viện. Kiểu dữ liệu, thuộc tính bắt buộc và giá trị mặc định luôn đồng bộ với mã nguồn.
Combobox
Component| Thuộc tính | Mô tả | Kiểu | Mặc định |
|---|---|---|---|
id | Id input (aria). | string | — |
optionsBắt buộc | Danh sách tuỳ chọn (string hoặc (label,value)). | ComboboxOption[] | Bắt buộc |
value | Giá trị đã chọn. | any | — |
onChangeBắt buộc | Hàm thay đổi (value). | (value: any) => void | Bắt buộc |
placeholder | Placeholder của trigger. | string | — |
className | Class tuỳ chỉnh cho trigger. | string | — |
disabled | Vô hiệu hoá. | boolean | false |
size | Kích thước. | FormControlSize | "md" |
variant | Biến thể hiển thị. | "default" | "outline" | "ghost" | "filled" | "default" |
allowClear | Hiển thị nút xoá lựa chọn. | boolean | false |
searchPlaceholder | Placeholder ô tìm kiếm (khi nhiều lựa chọn). | string | — |
emptyText | Văn bản khi không có kết quả. | string | — |
usePortal | Render dropdown bằng portal. | boolean | true |
getPortalContainer | Resolve the document element that should receive the dropdown portal. | () => HTMLElement | null | — |
label | Nhãn. | string | — |
labelClassName | Custom class for label | string | — |
required | Hiển thị dấu bắt buộc. | boolean | — |
fontBold | In đậm nhãn. | boolean | false |
loading | Mã nguồn chưa cung cấp mô tả bổ sung. | boolean | false |
loadingText | Mã nguồn chưa cung cấp mô tả bổ sung. | string | — |
borderMode | Mã nguồn chưa cung cấp mô tả bổ sung. | BorderMode | — |
showSelectedIcon | Mã nguồn chưa cung cấp mô tả bổ sung. | boolean | true |
maxHeight | Mã nguồn chưa cung cấp mô tả bổ sung. | number | 280 |
groupBy | Mã nguồn chưa cung cấp mô tả bổ sung. | (option: ComboboxOption) => string | — |
renderOption | Mã nguồn chưa cung cấp mô tả bổ sung. | (option: ComboboxOption, isSelected: boolean) => React.ReactNode | — |
renderValue | Mã nguồn chưa cung cấp mô tả bổ sung. | (option: ComboboxOption) => React.ReactNode | — |
selectedOption | Selected option fallback for manual/server search when options does not contain the current value. | ComboboxOption | — |
error | Mã nguồn chưa cung cấp mô tả bổ sung. | string | — |
helperText | Mã nguồn chưa cung cấp mô tả bổ sung. | string | — |
useOverlayScrollbar | Enable OverlayScrollbars on dropdown options list. Default: true when not virtualized | boolean | true |
virtualized | Virtualize large flat option lists. Grouped lists fall back to normal rendering. Default: false | boolean | false |
estimatedItemHeight | Estimated option row height used by virtualized rendering. Default: 44 | number | 44 |
overscan | Number of extra rows rendered above and below the visible range. Default: 8 | number | 8 |
enableSearch | Control whether the dropdown renders search UI and runs search logic. Defaults to automatic detection. | boolean | — |
searchMode | Use "manual" to let callers provide server-filtered options via onSearchChange. Default: "auto" | "auto" | "manual" | "auto" |
onSearchChange | Called whenever the search query changes. Required for manual/server search. | (query: string) => void | — |
searchDebounceMs | Debounce delay for onSearchChange. Default: 0 | number | 0 |
minSearchLength | Minimum query length before showing options in manual/search-prompt mode. Default: 0 | number | 0 |
maxInitialOptions | Limit the number of rendered options before the user types a query. | number | — |
showSearchPromptWhenEmptyQuery | Show a prompt instead of options while the query is shorter than minSearchLength. Default: false | boolean | false |
matchTriggerBackground | Match dropdown background to the computed background of the combobox trigger. Default: false | boolean | false |
Hướng dẫn sử dụng
Dùng Combobox khi lựa chọn có giới hạn nhanh và an toàn hơn nhập tự do. Cần cấu hình rõ locale, giới hạn, giá trị bị vô hiệu hóa và trạng thái xóa.
Trợ năng
Khi dùng Combobox, hãy giữ trạng thái focus dễ nhận biết, cung cấp tên truy cập khi cần và kiểm tra bàn phím cùng trình đọc màn hình trong ngữ cảnh thực tế.