0
# RC Tree
1

2
RC Tree is a comprehensive React tree component that enables developers to build hierarchical data displays with rich interactive features. It supports essential tree operations including node selection (single and multiple), checkboxes with strict and non-strict modes, drag-and-drop functionality, asynchronous data loading, virtual scrolling for performance, and extensive customization options for icons, styling, and behavior.
3

4
## Package Information
5

6
- **Package Name**: rc-tree
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript (React)
9
- **Installation**: `npm install rc-tree`
10

11
## Core Imports
12

13
```typescript
14
import Tree, { TreeNode } from "rc-tree";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Tree = require("rc-tree");
21
const { TreeNode } = require("rc-tree");
22
```
23

24
Additional imports:
25

26
```typescript
27
import Tree, { TreeNode, UnstableContext } from "rc-tree";
28
import type { TreeProps, TreeNodeProps, BasicDataNode, FieldDataNode } from "rc-tree";
29
```
30

31
CSS styling:
32

33
```javascript
34
import "rc-tree/assets/index.css";
35
```
36

37
## Basic Usage
38

39
```typescript
40
import React, { useState } from "react";
41
import Tree, { TreeNode } from "rc-tree";
42
import "rc-tree/assets/index.css";
43

44
const App = () => {
45
  const [expandedKeys, setExpandedKeys] = useState<string[]>(['0-0']);
46
  const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
47
  const [checkedKeys, setCheckedKeys] = useState<string[]>([]);
48

49
  return (
50
    <Tree
51
      checkable
52
      onExpand={(keys) => setExpandedKeys(keys)}
53
      expandedKeys={expandedKeys}
54
      onSelect={(keys) => setSelectedKeys(keys)}
55
      selectedKeys={selectedKeys}
56
      onCheck={(checked) => setCheckedKeys(Array.isArray(checked) ? checked : checked.checked)}
57
      checkedKeys={checkedKeys}
58
    >
59
      <TreeNode key="0-0" title="Root Node">
60
        <TreeNode key="0-0-0" title="Child Node 1" />
61
        <TreeNode key="0-0-1" title="Child Node 2" />
62
      </TreeNode>
63
    </Tree>
64
  );
65
};
66
```
67

68
## Architecture
69

70
RC Tree is built around several key components:
71

72
- **Tree Component**: Main container component managing tree state, interactions, and rendering
73
- **TreeNode Component**: Individual node component handling display and user interactions
74
- **Data Management**: Support for both JSX children and data-driven approaches via `treeData` prop
75
- **Virtual Scrolling**: Performance optimization for large trees using rc-virtual-list
76
- **Context System**: TreeContext for sharing configuration and event handlers across components
77
- **Utility System**: Comprehensive utilities for tree data manipulation, flattening, and transformations
78

79
## Capabilities
80

81
### Tree Component
82

83
Main tree container with comprehensive configuration options for rendering hierarchical data, handling user interactions, and managing tree state.
84

85
```typescript { .api }
86
interface TreeProps<TreeDataType extends BasicDataNode = DataNode> {
87
  prefixCls?: string; // Default: 'rc-tree'
88
  className?: string;
89
  style?: React.CSSProperties;
90
  children?: React.ReactNode;
91
  treeData?: TreeDataType[];
92
  // ... comprehensive configuration options
93
}
94

95
declare class Tree<TreeDataType extends BasicDataNode = DataNode> extends React.Component<TreeProps<TreeDataType>>;
96
```
97

98
[Tree Component](./tree-component.md)
99

100
### TreeNode Component
101

102
Individual tree node component for rendering nodes with titles, icons, checkboxes, and handling user interactions like selection and expansion.
103

104
```typescript { .api }
105
interface TreeNodeProps<TreeDataType extends BasicDataNode = DataNode> {
106
  eventKey?: Key;
107
  className?: string;
108
  style?: React.CSSProperties;
109
  title?: React.ReactNode | ((data: TreeDataType) => React.ReactNode);
110
  expanded?: boolean;
111
  selected?: boolean;
112
  checked?: boolean;
113
  // ... node-specific configuration
114
}
115

116
declare const TreeNode: React.FC<TreeNodeProps>;
117
```
118

119
[TreeNode Component](./tree-node.md)
120

121
### Data Management
122

123
Flexible data management supporting both JSX children and data-driven approaches with customizable field mappings and type-safe data structures.
124

125
```typescript { .api }
126
interface BasicDataNode {
127
  checkable?: boolean;
128
  disabled?: boolean;
129
  disableCheckbox?: boolean;
130
  icon?: IconType;
131
  isLeaf?: boolean;
132
  selectable?: boolean;
133
  switcherIcon?: IconType;
134
  className?: string;
135
  style?: React.CSSProperties;
136
}
137

138
type FieldDataNode<T, ChildFieldName extends string = 'children'> = BasicDataNode &
139
  T &
140
  Partial<Record<ChildFieldName, FieldDataNode<T, ChildFieldName>[]>>;
141

142
type DataNode = FieldDataNode<{
143
  key: Key;
144
  title?: React.ReactNode | ((data: DataNode) => React.ReactNode);
145
}>;
146
```
147

148
[Data Management](./data-management.md)
149

150
### Selection & Checking
151

152
Comprehensive selection and checking system with support for single/multiple selection, checkbox hierarchies, and strict/non-strict checking modes.
153

154
```typescript { .api }
155
interface CheckInfo<TreeDataType extends BasicDataNode = DataNode> {
156
  event: 'check';
157
  node: EventDataNode<TreeDataType>;
158
  checked: boolean;
159
  nativeEvent: MouseEvent;
160
  checkedNodes: TreeDataType[];
161
  checkedNodesPositions?: { node: TreeDataType; pos: string }[];
162
  halfCheckedKeys?: Key[];
163
}
164
```
165

166
[Selection & Checking](./selection-checking.md)
167

168
### Drag & Drop
169

170
Built-in drag and drop functionality with customizable drop validation, drag constraints, and comprehensive event handling for tree reorganization.
171

172
```typescript { .api }
173
interface AllowDropOptions<TreeDataType extends BasicDataNode = DataNode> {
174
  dragNode: TreeDataType;
175
  dropNode: TreeDataType;
176
  dropPosition: -1 | 0 | 1;
177
}
178

179
type AllowDrop<TreeDataType extends BasicDataNode = DataNode> = (
180
  options: AllowDropOptions<TreeDataType>,
181
) => boolean;
182

183
type DraggableConfig = {
184
  icon?: React.ReactNode | false;
185
  nodeDraggable?: (node: DataNode) => boolean;
186
};
187
```
188

189
[Drag & Drop](./drag-drop.md)
190

191
### Virtual Scrolling
192

193
Performance optimization for large tree datasets using virtual scrolling with configurable item heights and scroll behaviors.
194

195
```typescript { .api }
196
interface VirtualScrollProps {
197
  height?: number;
198
  itemHeight?: number;
199
  virtual?: boolean;
200
  scrollWidth?: number;
201
  itemScrollOffset?: number;
202
}
203
```
204

205
[Virtual Scrolling](./virtual-scrolling.md)
206

207
### Async Loading
208

209
Asynchronous data loading support for lazy-loading tree nodes with loading states and error handling.
210

211
```typescript { .api }
212
type LoadDataFunction<TreeDataType extends BasicDataNode = DataNode> = (
213
  treeNode: EventDataNode<TreeDataType>
214
) => Promise<any>;
215

216
interface LoadInfo<TreeDataType extends BasicDataNode = DataNode> {
217
  event: 'load';
218
  node: EventDataNode<TreeDataType>;
219
}
220
```
221

222
[Async Loading](./async-loading.md)
223

224
## Types
225

226
### Core Types
227

228
```typescript { .api }
229
type Key = React.Key;
230
type SafeKey = Exclude<Key, bigint>;
231

232
type IconType = React.ReactNode | ((props: TreeNodeProps) => React.ReactNode);
233

234
type Direction = 'ltr' | 'rtl' | undefined;
235

236
type ExpandAction = false | 'click' | 'doubleClick';
237

238
interface FieldNames {
239
  title?: string;
240
  _title?: string[];
241
  key?: string;
242
  children?: string;
243
}
244
```
245

246
### Event Types
247

248
```typescript { .api }
249
type NodeMouseEventHandler<
250
  TreeDataType extends BasicDataNode = DataNode,
251
  T = HTMLSpanElement,
252
> = (e: React.MouseEvent<T>, node: EventDataNode<TreeDataType>) => void;
253

254
type NodeDragEventHandler<
255
  TreeDataType extends BasicDataNode = DataNode,
256
  T = HTMLDivElement,
257
> = (e: React.DragEvent<T>, nodeProps: TreeNodeProps<TreeDataType>, outsideTree?: boolean) => void;
258

259
interface EventDataNode<TreeDataType> extends TreeDataType, BasicDataNode {
260
  key: Key;
261
  expanded: boolean;
262
  selected: boolean;
263
  checked: boolean;
264
  loaded: boolean;
265
  loading: boolean;
266
  halfChecked: boolean;
267
  dragOver: boolean;
268
  dragOverGapTop: boolean;
269
  dragOverGapBottom: boolean;
270
  pos: string;
271
  active: boolean;
272
}
273
```