# Tree

- Page: https://jiguang132.com/resources/arco-design/docs/tree
- Resource: Arco Design (https://jiguang132.com/resources/arco-design.md)
- All guides: https://jiguang132.com/resources/arco-design/docs.md

For content with many levels, such as folders, catalogs, and organizational structures, the tree can clearly show their hierarchical relationship, and has interactive functions such as expanding, collapsing, and selecting.

## Install

```bash
npm install @arco-design/web-react@2.66.18
```

Import `@arco-design/web-react/dist/css/arco.css` at the entry and set the locale with `ConfigProvider`. React 19 projects must also import `@arco-design/web-react/es/_util/react-19-adapter` first, or imperative APIs such as Message and Modal cannot render.

## Examples

- **Basic**: Give each `TreeNode` node a globally unique `key` (required), and the `title` is the content to be displayed on the node.
- **From TreeData**
- **BlockNode**: The treeNode occupy the remaining horizontal space.
- **Multiple Selection**: Add `multiple={true}` to `Tree` to enable multiple selection.
- **Checkable**: Add the `checkable` attribute to display the checkbox, and you can use `defaultCheckedKeys` to specify which nodes are checked by default.
- **Controlled**: You can specify the `selectedKeys` or `checkedKeys` or `expandedKeys` property of the tree to turn the tree into a controlled mode, and operate on the return value in the `onSelect` / `onCheck` / `onExpand` callback.
- **Dynamic Loading**: Load nodes dynamically.
- **Draggable**: Draggable nodes.
- **Checked Strategy**: Add `checkedStrategy` to set the return value when selected.
- **Show Line**: Add the `showLine` property to `Tree` to display the connecting line.
- **Size**
- **Node Icon**: The property `icon` of `TreeNode` can specify an icon for the node.
- **Extra Node**: The `renderExtra` property of `Tree` can customize node content.
- **Component Icons**: The components `loadingIcon`, `dragIcon`, and `switcherIcon` can be set through the `icons` property.
- **Virtual List**: By specifying `virtualListProps` to turn on the virtual list, high performance can be obtained when a large amount of data is used.
- **Searchable**
- **Customize treeData**: You can customize `treeData` by `fieldNames`.

Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews.

## API

### Tree

|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|autoExpandParent|Whether to automatically expand the parent node|boolean |`true`|-|
|blockNode|Whether to occupy the remaining horizontal space|boolean |`-`|-|
|checkable|Whether to add a checkbox before the node|boolean |`-`|-|
|checkStrictly|Whether to cancel the parent-child association|boolean |`-`|-|
|draggable|Whether the node can be dragged|boolean |`-`|-|
|multiple|Whether to support multiple selection|boolean |`-`|-|
|selectable|Whether can be selected|boolean |`true`|-|
|showLine|Whether to display the connection line|boolean |`-`|-|
|size|To set size|'mini' \| 'small' \| 'default' \| 'large' |`-`|-|
|actionOnClick|The action when click node|[ActionOnClick](#actiononclick) \| [ActionOnClick](#actiononclick)[] |`-`|select|
|allowDrop|Whether to allow dropping on node. (`dragNode` in `2.23.0`)|[AllowDrop](#allowdrop) |`() => true`|2.7.0|
|checkedKeys|The key of the checked node(controlled)|string[] |`-`|-|
|checkedStrategy|Customize the return value <br/> all: Return all selected nodes<br/> parent:Only return the parent node when both parent and child nodes are selected <br/> child: Return only child nodes|SHOW_ALL \| SHOW_PARENT \| SHOW_CHILD |`all`|-|
|className|Additional css class|string \| string[] |`-`|-|
|defaultCheckedKeys|The key of node checked by default|string[] |`-`|-|
|defaultExpandedKeys|The key of node expanded by default|string[] |`-`|-|
|defaultSelectedKeys|The key of node selected by default|string[] |`-`|-|
|expandedKeys|The key of the expanded node (controlled)|string[] |`-`|-|
|fieldNames|Custom field name for key, title, isLeaf, disabled and children|[FieldNamesType](#fieldnamestype) |`-`|2.11.0|
|halfCheckedKeys|the keys of half checked|string[] |`-`|2.27.0|
|loadMore|Callback when loaded data asynchronously, returning a `Promise`.|(node: [NodeInstance](#nodeinstance)) =&gt; Promise&lt;void&gt; |`-`|-|
|onDragEnd|Callback when the node ends drag|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDragLeave|Callback when the node leaves a valid target|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDragOver|Callback when the node is dragged onto a valid target|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDragStart|Callback when the node starts dragging|(e: DragEvent&lt;HTMLSpanElement&gt;, node: [NodeInstance](#nodeinstance)) =&gt; void |`-`|-|
|onDrop|Callback when the node is dropped on the valid target|(info: {e: DragEvent&lt;HTMLSpanElement&gt;;dragNode: [NodeInstance](#nodeinstance) \| null;dropNode: [NodeInstance](#nodeinstance) \| null;dropPosition: number;}) =&gt; void |`-`|-|
|selectedKeys|The key of the selected node(controlled)|string[] |`-`|-|
|style|Additional style|CSSProperties |`-`|-|
|treeData|The tree structure can be generated by passing in `treeData`|[TreeDataType](#treedatatype)[] |`-`|-|
|virtualListProps|Pass the virtual-list properties, pass in this parameter to turn on virtual scrolling|[AvailableVirtualListProps](#availablevirtuallistprops) |`-`|2.11.0|
|icons|Customize node icon|\| ((nodeProps: [NodeProps](tree#treenode)) => {dragIcon?: ReactNode;switcherIcon?: ReactNode;loadingIcon?: ReactNode;})\| {dragIcon?: ReactNode;switcherIcon?: ReactNode;loadingIcon?: ReactNode;} |`FieldNamesType`|2.9.0|
|onCheck|Callback when checked node|(checkedKeys: string[],extra: {node: [NodeInstance](#nodeinstance);checkedNodes: [NodeInstance](#nodeinstance)[];checked: boolean;halfCheckedKeys: string[];halfCheckedNodes: [NodeInstance](#nodeinstance)[];e: Event;}) => void |`-`|-|
|onExpand|Callback when expanded or collapsed node|(expandedKeys: string[],exra?: { expanded: boolean; node: [NodeInstance](#nodeinstance); expandedNodes: [NodeInstance](#nodeinstance)[] }) => void |`-`|-|
|onSelect|Callback when selected node|(selectedKeys: string[],extra: {selected: boolean;selectedNodes: [NodeInstance](#nodeinstance)[];node: [NodeInstance](#nodeinstance);e: Event;}) => void |`-`|-|
|renderExtra|Render additional node|(props: [NodeProps](tree#treenode)) => ReactNode |`-`|-|
|renderTitle|Customize title rendering|(props: [NodeProps](tree#treenode)) => ReactNode |`-`|-|

### Tree.Node

|Property|Description|Type|DefaultValue|
|---|---|---|---|
|checkable|Whether to show checkbox|boolean |`-`|
|disableCheckbox|Whether to disable check|boolean |`-`|
|disabled|Whether to disable node|boolean |`-`|
|draggable|Whether the current node can be dragged|boolean |`-`|
|isLeaf|Is it a leaf node. Effective when loading dynamically|boolean |`-`|
|selectable|Whether it can be selected|boolean |`true`|
|icons|Customize node icons, it have higher priority than Tree. When the icons property on the Tree is set at the same time, will be merged.|[TreeProps](tree#tree)['icons'] |`-`|
|icon|Custom icon|ReactNode |`-`|
|title|Title for node|string \| ReactNode |`-`|
|className|Additional css class|string \| string[] |`-`|
|style|Additional style|CSSProperties |`-`|

### AllowDrop

```js
export type AllowDrop = (options: {
  dropNode: NodeInstance;
  dragNode: NodeInstance | null;
  dropPosition: number;
}) => boolean;
```

### TreeDataType

```js
export type TreeDataType = NodeProps & {
  key?: string;
  _index?: number;
  children?: TreeDataType[];
  [key: string]: any;
};
```

### FieldNamesType

```js
export type FieldNamesType = {
  key?: string;
  title?: string;
  disabled?: string;
  children?: string;
  isLeaf?: string;
  disableCheckbox?: string;
  checkable?: string;
};
```

### AvailableVirtualListProps

```js
export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;
```

### ActionOnClick

```js
export type ActionOnClick = "select" | "check" | "expand";
```

### NodeInstance

```js
export type NodeInstance = ReactElement<
  PropsWithChildren<NodeProps>,
  typeof TreeNode
>;
```

### VirtualListProps

|Property|Description|Type|Default|
|---|:---:|:---:|---:|
|height|Viewable area height (`2.11.0` starts to support `string` type such as `80%`)|`number`| `200` |
|threshold|The threshold of the number of elements that automatically enable virtual scrolling, pass in `null` to disable virtual scrolling.|`number` \| `null`| `100` |
|isStaticItemHeight|Whether it is a static element of the same height|`boolean`|`true`|

---

Index of all JGuang resources: https://jiguang132.com/llms.txt