0
# TreeSelect Component
1

2
The main TreeSelect component providing a comprehensive tree selection interface with dropdown functionality, supporting both single and multiple selection, checkable nodes, search, async loading, and performance optimizations.
3

4
## Capabilities
5

6
### TreeSelect Component
7

8
Main tree-select component with generic type parameters for value and option types.
9

10
```typescript { .api }
11
/**
12
 * Main TreeSelect component for hierarchical data selection
13
 * @template ValueType - Type of the selection value(s) 
14
 * @template OptionType - Type of tree node data extending DataNode
15
 */
16
declare const TreeSelect: <ValueType = any, OptionType extends DataNode = DataNode>(
17
  props: TreeSelectProps<ValueType, OptionType> & React.RefAttributes<BaseSelectRef>
18
) => React.ReactElement;
19

20
interface TreeSelectProps<ValueType = any, OptionType extends DataNode = DataNode> {
21
  // Basic configuration
22
  prefixCls?: string;
23
  id?: string;
24
  className?: string;
25
  style?: React.CSSProperties;
26
  disabled?: boolean;
27
  placeholder?: string;
28
  
29
  // Value management
30
  value?: ValueType;
31
  defaultValue?: ValueType;
32
  onChange?: (value: ValueType, labelList: React.ReactNode[], extra: ChangeEventExtra) => void;
33
  labelInValue?: boolean;
34
  maxCount?: number;
35
  
36
  // Selection configuration  
37
  multiple?: boolean;
38
  treeCheckable?: boolean | React.ReactNode;
39
  treeCheckStrictly?: boolean;
40
  showCheckedStrategy?: CheckedStrategy;
41
  
42
  // Data source
43
  treeData?: OptionType[];
44
  children?: React.ReactNode;
45
  treeDataSimpleMode?: boolean | SimpleModeConfig;
46
  fieldNames?: FieldNames;
47
  
48
  // Tree expansion
49
  treeDefaultExpandAll?: boolean;
50
  treeExpandedKeys?: SafeKey[];
51
  treeDefaultExpandedKeys?: SafeKey[];
52
  onTreeExpand?: (expandedKeys: SafeKey[]) => void;
53
  treeExpandAction?: ExpandAction;
54
  
55
  // Search & filtering
56
  searchValue?: string;
57
  /** @deprecated Use searchValue instead */
58
  inputValue?: string;
59
  onSearch?: (value: string) => void;
60
  autoClearSearchValue?: boolean;
61
  filterTreeNode?: boolean | ((inputValue: string, treeNode: DataNode) => boolean);
62
  treeNodeFilterProp?: string;
63
  treeNodeLabelProp?: string;
64
  
65
  // Async loading
66
  loadData?: (dataNode: LegacyDataNode) => Promise<unknown>;
67
  treeLoadedKeys?: SafeKey[];
68
  onTreeLoad?: (loadedKeys: SafeKey[]) => void;
69
  
70
  // Tree appearance
71
  treeTitleRender?: (node: OptionType) => React.ReactNode;
72
  treeLine?: boolean;
73
  treeIcon?: IconType;
74
  showTreeIcon?: boolean;
75
  switcherIcon?: IconType;
76
  treeMotion?: any;
77
  
78
  // Dropdown configuration
79
  open?: boolean;
80
  onDropdownVisibleChange?: (open: boolean) => void;
81
  dropdownStyle?: React.CSSProperties;
82
  dropdownClassName?: string;
83
  dropdownMatchSelectWidth?: boolean | number;
84
  dropdownAlign?: AlignType;
85
  getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;
86
  
87
  // Performance & virtualization
88
  virtual?: boolean;
89
  listHeight?: number;
90
  listItemHeight?: number;
91
  listItemScrollOffset?: number;
92
  
93
  // Event handlers
94
  onSelect?: (value: ValueType, option: OptionType) => void;
95
  onDeselect?: (value: ValueType, option: OptionType) => void;
96
  onClear?: () => void;
97
  onFocus?: (e: React.FocusEvent) => void;
98
  onBlur?: (e: React.FocusEvent) => void;
99
  onPopupScroll?: (e: React.UIEvent) => void;
100
  
101
  // Additional props
102
  allowClear?: boolean;
103
  showSearch?: boolean;
104
  notFoundContent?: React.ReactNode;
105
  maxTagCount?: number | 'responsive';
106
  maxTagPlaceholder?: React.ReactNode;
107
  maxTagTextLength?: number;
108
  loading?: boolean;
109
  direction?: 'ltr' | 'rtl';
110
  tabIndex?: number;
111
}
112
```
113

114
### Component Reference Methods
115

116
TreeSelect exposes methods through React ref for programmatic control.
117

118
```typescript { .api }
119
interface BaseSelectRef {
120
  /** Focus the select input */
121
  focus: () => void;
122
  /** Remove focus from the select input */
123
  blur: () => void;
124
  /** Scroll to specific position in dropdown list */
125
  scrollTo: (config: ScrollConfig) => void;
126
}
127

128
interface ScrollConfig {
129
  index?: number;
130
  key?: SafeKey;
131
  align?: 'top' | 'bottom' | 'auto';
132
  offset?: number;
133
}
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
import TreeSelect from "rc-tree-select";
140
import { useRef } from "react";
141

142
// Single selection with tree data
143
function SingleSelectExample() {
144
  const [value, setValue] = useState("0-0-0");
145
  
146
  const treeData = [
147
    {
148
      key: "0-0",
149
      value: "0-0", 
150
      title: "Parent Node",
151
      children: [
152
        { key: "0-0-0", value: "0-0-0", title: "Child Node 1" },
153
        { key: "0-0-1", value: "0-0-1", title: "Child Node 2" },
154
      ],
155
    },
156
  ];
157

158
  return (
159
    <TreeSelect
160
      style={{ width: 300 }}
161
      value={value}
162
      treeData={treeData}
163
      treeDefaultExpandAll
164
      onChange={setValue}
165
      placeholder="Select node"
166
    />
167
  );
168
}
169

170
// Multiple selection with checkboxes
171
function MultipleSelectExample() {
172
  const [value, setValue] = useState<string[]>([]);
173
  
174
  return (
175
    <TreeSelect
176
      style={{ width: 300 }}
177
      value={value}
178
      treeData={treeData}
179
      multiple
180
      treeCheckable
181
      showCheckedStrategy={SHOW_PARENT}
182
      placeholder="Select multiple nodes"
183
      onChange={setValue}
184
    />
185
  );
186
}
187

188
// Async data loading
189
function AsyncLoadingExample() {
190
  const [value, setValue] = useState();
191
  
192
  const loadData = (node: DataNode) => {
193
    return new Promise<void>((resolve) => {
194
      setTimeout(() => {
195
        // Simulate async data loading
196
        node.children = [
197
          { key: `${node.key}-0`, value: `${node.key}-0`, title: 'Child 1' },
198
          { key: `${node.key}-1`, value: `${node.key}-1`, title: 'Child 2' },
199
        ];
200
        resolve();
201
      }, 1000);
202
    });
203
  };
204

205
  return (
206
    <TreeSelect
207
      style={{ width: 300 }}
208
      value={value}
209
      treeData={[
210
        { key: "0", value: "0", title: "Expandable Node", isLeaf: false },
211
      ]}
212
      loadData={loadData}
213
      onChange={setValue}
214
    />
215
  );
216
}
217

218
// Search and filtering
219
function SearchableExample() {
220
  const [value, setValue] = useState();
221
  const [searchValue, setSearchValue] = useState("");
222
  
223
  return (
224
    <TreeSelect
225
      style={{ width: 300 }}
226
      value={value}
227
      searchValue={searchValue}
228
      treeData={treeData}
229
      showSearch
230
      filterTreeNode={(inputValue, treeNode) =>
231
        treeNode.title?.toString().toLowerCase().includes(inputValue.toLowerCase())
232
      }
233
      onChange={setValue}
234
      onSearch={setSearchValue}
235
      placeholder="Search and select"
236
    />
237
  );
238
}
239

240
// LabelInValue mode
241
function LabelInValueExample() {
242
  const [value, setValue] = useState<{ label: string; value: string }>();
243
  
244
  return (
245
    <TreeSelect
246
      style={{ width: 300 }}
247
      value={value}
248
      treeData={treeData}
249
      labelInValue
250
      treeDefaultExpandAll
251
      onChange={setValue}
252
      placeholder="Select with label"
253
    />
254
  );
255
}
256

257
// Using ref methods  
258
function RefMethodsExample() {
259
  const selectRef = useRef<BaseSelectRef>(null);
260
  
261
  const handleFocus = () => {
262
    selectRef.current?.focus();
263
  };
264
  
265
  return (
266
    <div>
267
      <button onClick={handleFocus}>Focus TreeSelect</button>
268
      <TreeSelect
269
        ref={selectRef}
270
        style={{ width: 300 }}
271
        treeData={treeData}
272
        placeholder="Controlled focus"
273
      />
274
    </div>
275
  );
276
}
277
```
278

279
## Types
280

281
```typescript { .api }
282
// Change event information
283
interface ChangeEventExtra {
284
  preValue: SafeKey[];
285
  triggerValue: SafeKey;
286
  triggerNode: DataNode;
287
  selected?: boolean;
288
  checked?: boolean;
289
}
290

291
// Icon type for tree display  
292
type IconType = React.ReactNode | ((props: any) => React.ReactNode);
293

294
// Legacy data node for backward compatibility
295
interface LegacyDataNode extends DataNode {
296
  props?: any;
297
}
298

299
// Expand action type for tree interactions
300
type ExpandAction = 'click' | 'doubleClick';
301

302
// Alignment configuration for dropdown positioning
303
interface AlignType {
304
  points?: string[];
305
  offset?: number[];
306
  targetOffset?: number[];
307
  overflow?: {
308
    adjustX?: boolean;
309
    adjustY?: boolean;
310
  };
311
}
312
```