ComponentPicker & Select
Bắt đầu nhanh
Import CategoryTreeSelect từ entry công khai. 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 { CategoryTreeSelect } from '@underverse-ui/underverse';Ví dụ tương tác
Dùng thử CategoryTreeSelect 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.
CategoryTreeSelect
Component| Thuộc tính | Mô tả | Kiểu | Mặc định |
|---|---|---|---|
singleSelect | Chỉ cho phép chọn 1 node. | false | — |
value | Selected category ids. Selected category id or `null` when nothing is selected. | number[] | — |
onChange | Called with the full selected id list. Called with the selected id or `null`. | (selectedIds: number[]) => void | — |
id | Mã nguồn chưa cung cấp mô tả bổ sung. | string | — |
label | Optional field label rendered above the control. | string | — |
labelClassName | Extra classes for the label element. | string | — |
categoriesBắt buộc | Flat category list. Parent/child relationships are resolved via `parent_id`. | Category[] | Bắt buộc |
placeholder | Placeholder text when no category is selected. | string | — |
disabled | Disables interaction and fades the control. | boolean | — |
required | Participate in form-required validation. | boolean | — |
size | Visual size of the trigger. | FormControlSize | — |
variant | Visual style of the trigger. | "default" | "outline" | "ghost" | "filled" | — |
allowClear | Show a clear button when a selection exists. | boolean | — |
error | External error message. Takes precedence over helper text. | string | — |
helperText | Helper text shown below the field when there is no error. | string | — |
viewOnly | When true, renders as a read-only tree view without selection behavior. | boolean | — |
defaultExpanded | Expand every parent node by default. | boolean | — |
defaultExpandedIds | Explicit branch ids that should start expanded in uncontrolled mode. | number[] | — |
expandToId | Expand the ancestor path so a specific node is visible by default. | number | null | — |
expandedIds | Controlled expanded branch ids. | number[] | — |
onExpandedChange | Called whenever expand/collapse changes the expanded branch ids. | (expandedIds: number[]) => void | — |
enableSearch | Enable search input for filtering categories. Default: auto-enabled when `categories.length > 10` (similar to MultiCombobox). | boolean | — |
labels | Replace built-in labels for localization or custom wording. | CategoryTreeSelectLabels | — |
inline | Render the tree directly instead of inside a dropdown trigger. | boolean | — |
onNodeClick | Called when a node row is clicked. Useful for navigation flows. | (node: Category) => void | — |
className | Custom class for the outer tree container. | string | — |
useOverlayScrollbar | Enable OverlayScrollbars for the dropdown tree viewport. Default: `false`. | boolean | — |
leafOnlySelect | When true, only leaf nodes can be selected; parent nodes only expand/collapse. | boolean | — |
virtualized | Virtualize the dropdown tree by rendering only visible rows. Inline/view-only trees keep recursive rendering. | boolean | — |
estimatedItemHeight | Estimated tree row height used by virtualized rendering. Default: `36`. | number | — |
overscan | Number of extra rows rendered above and below the visible range. Default: `8`. | number | — |
maxInitialOptions | Limit the number of rendered rows before the user types a query. | number | — |
searchMode | Use `"manual"` to let callers provide server-filtered categories via `onSearchChange`. Default: `"auto"`. | "auto" | "manual" | — |
onSearchChange | Called whenever the search query changes. Useful for manual/server search. | (query: string) => void | — |
searchDebounceMs | Debounce delay for `onSearchChange`. Default: `0`. | number | — |
minSearchLength | Minimum query length before showing options in manual/search-prompt mode. Default: `0`. | number | — |
showSearchPromptWhenEmptyQuery | Show a prompt instead of options while the query is shorter than `minSearchLength`. Default: `false`. | boolean | — |
renderItemActions | Render custom actions at the trailing edge of each tree row. | (category: Category) => React.ReactNode | — |
baseIndent | Base left padding in rem applied to every node regardless of depth. Default: `0`. | number | — |
indentSize | Additional left padding in rem added per depth level. Default: `0.75`. | number | — |
showTreeLines | Show dashed vertical guide lines between parent and child levels. Default: `true`. | boolean | — |
borderMode | Mã nguồn chưa cung cấp mô tả bổ sung. | BorderMode | — |
Hướng dẫn sử dụng
Dùng CategoryTreeSelect 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 CategoryTreeSelect, 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ế.