Skip to content

Design system

Documentation

DesignComponents / TreeSelect

Components / TreeSelect

Stable

TreeSelect

Choose one or more hierarchical values from a searchable tree popup.

On this page

Examples

Single nested choice

Choose a node while preserving its complete parent hierarchy.

Team

Single team selection

Multiple choices

Select several nodes without closing the popup after each choice.

Teams to notify

Multiple team selection

Read-only and disabled

Keep the current value visible while distinguishing non-editable and unavailable states.

Read-only team

Selection is read-only.

Unavailable team

TreeSelect read-only and disabled states

Try TreeSelect

Inspect the bounded popup and hierarchical selection.

Team

TreeSelect property playground

Usage

import { TreeSelect } from "@phuctech/ui/components/tree-select";

<TreeSelect label="Team" nodes={teams} value={teamId} onValueChange={setTeamId} />

Without onSearch, TreeSelect filters plain text and textValue locally while retaining matching ancestors. With onSearch, it debounces the callback between 300 and 500 ms (350 ms default); the feature supplies new nodes, loading, and error state. The feature must protect asynchronous results from races and can batch requests. It does not fetch data or virtualize a large tree.

API

Component API
PropTypeDefaultDescriptionConstraints
label / nodesstring / readonly TreeNode[]requiredVisible field label and tree choices.Use stable node IDs and textValue for non-text labels.
value / defaultValuestring | readonly string[]unselectedControlled or initial single/multiple selection.Use strings in single mode and arrays in multiple mode.
multiplebooleanfalseAllows multiple node selection.The popup remains open after each selection.
onValueChange(value: string | readonly string[] | undefined) => void—Receives the next value.The feature owns persistence and domain validation.
query / defaultQuery / onQueryChangestring / callback""Controlled or uncontrolled search input state.Use both callback props for a fully controlled query.
onSearch / searchDebounceMscallback / number350 msDebounced query handoff for consumer-supplied results.Delay is clamped to 300–500 ms; the feature owns loading, errors, and race protection.
loading / error / emptyMessageboolean / ReactNode / ReactNodefalse / — / default messageConsumer-owned request feedback and empty result text.Do not use empty state while loading or while an error is shown.
disabled / readOnly / name / formboolean / boolean / string / stringfalse / false / — / —Interaction and native hidden-input integration.Multiple mode submits one hidden value per selected node.

Accessibility

The trigger is named from the visible label and current value. The popup contains a named Tree; the tree supports arrow, Home/End, Enter, and Space behavior and announces branch expansion and selection. The search field has a specific accessible name.

  • Tree presents an always-visible hierarchy.
  • Cascader selects a single path through level-by-level columns.
  • Combobox searches a flat option set.