ComponentPicker & Select
MultiCombobox
MultiCombobox 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 MultiCombobox 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 { MultiCombobox } from '@underverse-ui/underverse';Ví dụ tương tác
Dùng thử MultiCombobox 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.
MultiCombobox
Component| Thuộc tính | Mô tả | Kiểu | Mặc định |
|---|---|---|---|
id | Id input (aria). | string | — |
optionsBắt buộc | Tuỳ chọn (string hoặc (value,label)). | Array<string | MultiComboboxOption> | Bắt buộc |
valueBắt buộc | Các giá trị đã chọn (mảng). | string[] | Bắt buộc |
onChangeBắt buộc | Hàm thay đổi (mảng). | (value: string[]) => void | Bắt buộc |
placeholder | Placeholder. | string | — |
searchPlaceholder | Mã nguồn chưa cung cấp mô tả bổ sung. | string | — |
maxSelected | Số mục tối đa. | number | — |
disabledOptions | Các giá trị không cho chọn. | string[] | [] |
showTags | Hiển thị tag các lựa chọn. | boolean | true |
showClear | Hiển thị nút xoá. | boolean | true |
className | Class tuỳ chỉnh cho wrapper. | string | — |
disabled | Vô hiệu hoá. | boolean | false |
size | Kích thước. | FormControlSize | "md" |
variant | Mã nguồn chưa cung cấp mô tả bổ sung. | "default" | "outline" | "ghost" | "default" |
label | Nhãn. | string | — |
labelClassName | Custom class for label | string | — |
title | Tiêu đề phía trên control. | string | — |
required | Hiển thị bắt buộc. | boolean | — |
displayFormat | Định dạng label hiển thị. | (option: MultiComboboxOption) => string | (option) => option.label |
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 | — |
emptyText | 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 | — |
showSelectedIcons | 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: MultiComboboxOption) => string | — |
renderOption | Mã nguồn chưa cung cấp mô tả bổ sung. | (option: MultiComboboxOption, isSelected: boolean) => React.ReactNode | — |
renderTag | Mã nguồn chưa cung cấp mô tả bổ sung. | (option: MultiComboboxOption, onRemove: () => void) => React.ReactNode | — |
selectedOptions | Selected option fallbacks for manual/server search when options does not contain current values. | MultiComboboxOption[] | — |
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 | — |
maxTagsVisible | Mã nguồn chưa cung cấp mô tả bổ sung. | number | 3 |
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 |
getPortalContainer | Resolve the document element that should receive the options dropdown portal. | () => HTMLElement | null | — |
Hướng dẫn sử dụng
Dùng MultiCombobox 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 MultiCombobox, 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ế.