Tree

Multiple-level structure list.

When To Use

Almost anything can be represented in a tree structure. Examples include directories, organization hierarchies, biological classifications, countries, etc. The Tree component is a way of representing the hierarchical relationship between these things. You can also expand, collapse, and select a treeNode within a Tree.

Examples

• Basic · basic

• Controlled Tree · basic-controlled

• draggable · draggable

• load data asynchronously · dynamic

• Searchable · search

• Tree with line · line

• Customize Icon · customized-icon

• directory · directory

• Customize collapse/expand icon · switcher-icon

• Virtual scroll · virtual-scroll

• Scroll to nested node · scroll-to

• Block Node · block-node

• Custom semantic dom styling · style-class

API

Common props ref：Common props

Tree props

TreeNode props

DirectoryTree props

Note

Before 3.4.0: The number of treeNodes can be very large, but when checkable=true, it will increase the compute time. So, we cache some calculations (e.g. this.treeNodesStates) to avoid double computing. But, this brings some restrictions. When you load treeNodes asynchronously, you should render tree like this:

{
  this.state.treeData.length ? (
    <Tree>
      {this.state.treeData.map((data) => (
        <TreeNode />
      ))}
    </Tree>
  ) : (
    'loading tree'
  );
}

Tree Methods

Tree Hooks

Tree.useTree

type Tree.useTree = (treeData: DataNode[], config: { fieldNames?: FieldNames }) => TreeInstance

Provides Tree data utilities. getPath(key) returns the node entities from the root to the target node, which can be used to update expandedKeys in controlled mode.

getPath has a stable function identity and reads the latest treeData when called. If you memoize a value derived from getPath, include treeData and the lookup key in the dependency list because dependency tracking cannot observe the data captured inside getPath.

const { getPath } = Tree.useTree(treeData, {});

const path = useMemo(() => getPath(selectedKey), [getPath, selectedKey, treeData]);

Semantic DOM

Semantic description source: vendor/components/tree/demo/_semantic.tsx

Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

Declaration source: vendor/components/tree/style/index.ts

import type { CSSInterpolation, CSSObject } from '@ant-design/cssinjs';

import { Keyframes, unit } from '@ant-design/cssinjs';

import { getStyle as getCheckboxStyle } from '../../checkbox/style';

import { genFocusOutline, resetComponent } from '../../style';

import { genCollapseMotion } from '../../style/motion';

import type { AliasToken, CSSUtil, FullToken, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import { genDirectoryStyle } from './directory';

export interface TreeSharedToken {
  /**
   * @desc 节点标题高度
   * @descEN Node title height
   */
  titleHeight: number;
  /**
   * @desc 展开按钮宽度
   * @descEN Switcher width of tree
   */
  switcherSize?: number;
  /**
   * @desc 缩进宽度
   * @descEN Indent width of tree
   */
  indentSize?: number;
  /**
   * @desc 节点悬浮态背景色
   * @descEN Background color of hovered node
   */
  nodeHoverBg: string;
  /**
   * @desc 节点悬浮态态文字颜色
   * @descEN Text color of hovered node
   */
  nodeHoverColor: string;
  /**
   * @desc 节点选中态背景色
   * @descEN Background color of selected node
   */
  nodeSelectedBg: string;
  /**
   * @desc 节点选中态文字颜色
   * @descEN Text color of selected node
   */
  nodeSelectedColor: string;
}

export interface ComponentToken extends TreeSharedToken {
  /**
   * @desc 目录树节点选中文字颜色
   * @descEN Text color of selected directory node
   */
  directoryNodeSelectedColor: string;
  /**
   * @desc 目录树节点选中背景色
   * @descEN Background color of selected directory node
   */
  directoryNodeSelectedBg: string;
}

// =============================== Base ===============================
export type TreeToken = FullToken<'Tree'> & {
  treeCls: string;
  treeNodeCls: string;
  treeNodePadding: number | string;
};

FAQ

Why defaultExpandAll not working on ajax data?

default prefix props only work when initializing. So defaultExpandAll has already been executed when ajax loads data. You can control expandedKeys or render the Tree when data is loaded to realize expanding all nodes.

Virtual scroll limitation

Virtual scroll only render items in visible region. Thus not support auto width (like long title with horizontal scroll).

What does disabled node work logic in the tree?

Tree change its data by conduction. Includes checked or auto expanded, it will conduction state to parent / children node until current node is disabled. So if a controlled node is disabled, it will only modify self state and not affect other nodes. For example, a parent node contains 3 child nodes and one of them is disabled. When check the parent node, it will only check rest 2 child nodes. As the same, when check these 2 child node, parent will be checked whatever checked state the disabled one is.

This conduction logic prevents modifying disabled parent checked state by checking children nodes, and users cannot modify directly with click which avoids interactive conflicts. If you want to modify this conduction logic, you can customize it with the checkStrictly prop.

Shared native props

Tips: The following generic properties apply to most antd components; those not supported are described separately.

Install and reproduce an example

npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

• vendor/components/tree/DirectoryTree.tsx
• vendor/components/tree/Tree.tsx
• vendor/components/tree/index.tsx
• vendor/components/tree/style/index.ts
• vendor/components/tree/utils/dictUtil.ts
• vendor/components/tree/utils/dropIndicator.tsx
• vendor/components/tree/utils/iconUtil.tsx

Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.