Navigation · Tree
Tree
A tree view component presents a hierarchical list.

Demos

How to import

Basic Usage

By default, tree is in single select mode and each item is selectable.

Multi-choice

You could use multiple to set mode to multi-choice. When all child items are selected, the parent item will be selected.

Searchable

Use filterTreeNode to support search input. By default it searches the label property of the data. You can use treeNodeFilterProp to set another property to search or pass in a function to filterTreeNode to customize search behavior.
You could also use showFilteredOnly if you prefer to display filtered results only.
After setting the filterTreeNode property to enable search, you can customize the rendering method of the search box by setting searchRender. When set to false, the search box can be hidden.

Trigger search manually

Use ref to get tree instance,you can call search method of tree to trigger search manually. Note that you need to set filterTreeNode to enable search at the same time.If the search box is outside the tree, you can hide the search box inside the tree by setting searchRender=false.

JSON TreeData

You could use treeDataSimpleJson to pass in treeNodes data in JSON format. In this case, key will be used as key and label, and value will be used as value correspondingly. Return value includes JSON data in selected nodes.

BlockNode

You could use blockNode to set node to display as a row. In this case, styles for hovering and selected state take effects on the entire row. By default, it is set to true. When it is set to false, only label will be highlighted.

Custom TreeNode Label

You could pass in ReactNode for label in treeNode to customize label. Pay attention that by default filterTreeNode searches data by label. When label is a ReactNode, it is advised to pass in customized search function for a searchable tree.

Custom Icon

You could use icon to add customized icon.

Directory

You could use directory to display tree as a directory with default icons. Also, the icon could be overwritten by custom Icon.

Disabled

You can use disableStrictly to set whether to enable strict disabling. After enabling strict disabling, when the node is disabled, the selected state cannot be changed through the relationship between the child or the parent.

Checked RelationShip

Version: >= 2.5.0
When multiple selections are made, checkRelation can be used to set the type of node selection relationship, optional: 'related' (default), 'unRelated'. When the selection relationship is 'unRelated', it means that selections between nodes do not affect each other.

Default Expand All

Both defaultExpandAll and expandAll can set the default expanded/collapsed state of Tree. The difference between the two is that defaultExpandAll only takes effect at initialization, while expandAll will not only take effect at initialization, but also when the data (treeData/treeDataSimpleJson) is dynamically updated, expandAll will still take effect.
Among them, expandAll is supported starting from 1.30.0.
In the demo below, after clicking the button to update TreeData, defaultExpandAll becomes invalid, and expandAll still takes effect.

Controlled Component

You can use value along with onChange property if you want to use Tree as a controlled component.

Auto Expand Parent

In the case of controlled expansion, when autoExpandParent is turned on, if you want to collapse the parent element, you need to collapse all its child elements. By default, autoExpandParent is false, that is, the collapse of the parent element is not affected by the child element.

Virtualized Tree

If you need to render large sets of tree structured data, you could use virtualized tree. In virtualized mode, animation / motion is disabled for better performance.
The property virtualize is an object consisting of the following values:
  • height: Height of the tree, If passed in as a string, computed height should not be zero for render purpose, in other words, parent node should have offsetHeight
  • width: Width of the tree.
  • itemSize: Height for each line of treeNode, required
If tree is searchable, you could also set showFilteredOnly={true} to reduce time of rendering for results.

Dynamic Update of Data

Load Data Asynchronously

You could use loadData to load treeData asynchronously on node expansion. Notice isLeaf is required to mark node as leaf in treeData.

Draggable Tree

You could use draggable along with onDrop to achieve a draggable Tree.
Notice
Drag and drop is available since v 1.8.0. Simultaneous use with virtualization is currently not supported
The callback input parameters of the drag event are as follows:
The node, in addition to the original data originalData, also contains:
  • pos refers to the positional relationship of the current node in the entire treeData, such as the 0th node of the 2nd node of the 1st node of the 0th layer: '0-1-2-0'
  • dropPosition refers to the position where the dragged node is dropped in the current hierarchy. If it is inserted before the 0th node of the same level, it will be -1, and after the 0th node, it will be 1, and it will fall on it. is 0, and so on. With dropToGap, a more complete judgment can be obtained.
  • dropToGap refers to whether the dragged node is dropped between nodes, if false, it is dropped above a node

Advanced FullRender

v>=1.7.0
You could use renderFullLabel for advanced rendering to render the entire option on you own.
Important
If virtualized is set to true, be sure to apply `style` to targeted ReactNode to correctly render virtualized list.
Here are some demos.
First is to render Parent node as separator and only allow leaf nodes to be selected.
renderFullLabel only takes care of the UI rendering and won't affect inside data logic. But you could choose info to your needs and use it with controlled mode for advanced usage.
The second is for the scenario of "I hope that only leaf nodes can be single-selected, and the parent node only plays a role in grouping".
  • You only need to click on the parent node without triggering the selection, click on the leaf node to trigger.
Third is for the scenario when selecting Parent node also highlighting child node.

Advanced FullRender with Draggable

Starting from version 1.27.0, we support the simultaneous use of draggable (draggable) and advanced customization (renderFullLabel). Before this version, the simultaneous use of both was not supported.

API Reference

Tree

PropertiesInstructionsTypeDefaultVersion
autoExpandParentToggle whether to expand parent node automaticallybooleanfalse0.34.0
autoExpandWhenDragEnterToggle whether allow autoExpand when drag enter nodebooleantrue1.8.0
blockNodeToggle whether to display node as rowbooleantrue-
checkRelationIn multiple, the relationship between the checked states of the nodes, optional: 'related'、'unRelated'string'related'2.5.0
classNameClass namestring--
defaultExpandAllSet whether to expand all nodes during initialization. And if the subsequent data (treeData/treeDataSimpleJson) changes, this api cannot affect the default expansion of the node. If you need this, you can use expandAllbooleanfalse-
defaultExpandedKeysKeys of default expanded nodes. Direct child nodes will be displayed.string[]--
defaultValueDefault valuestring | number | TreeNode | (string | number | TreeNode)[]--
directoryToggle whether to display tree in directory modebooleanfalse-
disableStrictlyWhen a node is disabled, its status could not be changed by its parent or child nodesbooleanfalse1.4.0
disabledToggle whether to disable the entire tree to be unselectablebooleanfalse0.32.0
draggableToggle whether allow draggablebooleanfalse1.8.0
emptyContentEmpty content when no dataReactNodeno result0.32.0
expandActionExpand logic, one of false, 'click', 'doubleClick'. Default is set to false, which means item will not be expanded on clicking except on expand iconboolean | stringfalse0.35.0
expandAllSet whether to expand all nodes by default. If the subsequent data (treeData/treeDataSimpleJson) changes, the default expansion will also be affected by this apibooleanfalse1.30.0
expandedKeys(Controlled)Keys of expanded nodes. Direct child nodes will be displayed.string[]--
filterTreeNodeToggle whether searchable or pass in a function to customize search behavior.boolean | ((inputValue: string, treeNodeString: string) => boolean)false-
hideDraggingNodeToggle whether to hide dragImg of dragging nodebooleanfalse1.8.0
iconIconReactNode--
labelEllipsisToggle whether to ellipsis label when overflow. Set to false iff there are other requirementsbooleanfalse|true(virtualized)1.8.0
leafOnlyToggle whether to display tags for leaf nodes only and for onChange callback params in multiple modebooleanfalse1.18.0
loadDataLoad data asynchronously and the return value should be a promise(treeNode?: TreeNode) => Promise< void >-1.0.0
loadedKeys(Controlled)Mark node as loaded, working with loadDatastring[]-1.0.0
motionToggle whether to turn on animationbooleantrue-
multipleToggle whether in multi-choice modebooleanfalse-
preventScrollIndicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the userboolean
renderDraggingNodeCustom render function to render html element of dragImg for dragging node(nodeInstance: HTMLElement, node: TreeNode) => HTMLElement-1.8.0
renderFullLabelCustom option render function(data: object) => ReactNode-1.7.0
renderLabelCustom label render function(label: ReactNode, data: TreeNode) => ReactNode-1.6.0
searchClassNameClassname property for search boxstring--
searchPlaceholderPlaceholder for search boxstring--
searchRenderCustom method to render search input; hide search box if set to false(V>=1.0.0)((searchRenderProps: object) => ReactNode) | false-0.35.0
searchStyleStyle for for search boxCSSProperties--
showClearToggle whether to support clear input boxbooleantrue0.35.0
showFilteredOnlyToggle whether to displayed filtered result only in search modebooleanfalse0.32.0
styleInline styleCSSProperties--
treeDataData for treeNodesTreeNode[][]-
treeDataSimpleJsonData for treeNodes in JSON format, return value in JSON format as wellTreeDataSimpleJson{}-
treeNodeFilterPropProperty in a treeNode used to searchstringlabel-
valueCurrent value, used when tree is a controlled componentstring | number | TreeNode | (string | number | TreeNode)[]--
virtualizeEfficiently rendering large lists, refer to VirtualizeObj. Motion is disabled when tree is rendered as virtualized list.VirtualizeObj-0.32.0
onChangeCallback function when the tree node is selected, return the value property of data(string | number | TreeNode | (string | number | TreeNode)[]) => void--
onChangeWithObjectToggle whether to return all properties in an option as a return value. When set to true, return value looks like: { value, label, ...rest }. For controlled mode, you need to pass an object with { value: value } to value correspondingly. DefaultValue similarly.booleanfalse-
onDoubleClick(e: MouseEvent, node: TreeNode) => void-0.35.0
onDragEndCallback function for onDragEnd(dragProps: object) => void-1.8.0
onDragEnterCallback function for onDragEnter(dragEnterProps: object) => void-1.8.0
onDragLeaveCallback function for onDragLeave(dragProps: object) => void-1.8.0
onDragOverCallback function for onDragOver(dragProps: object) => void-1.8.0
onDragStartCallback function for onDragStart(dragProps: object) => void-1.8.0
onDropCallback function for onDrop(onDragProps: object) => void-1.8.0
onExpandCallback function when expand or collapse a node(expandedKeys: string[], {expanded: boolean, node: TreeNode}) => void--
onLoadCallback function when a node is loaded(loadedKeys: Set< string >, treeNode: TreeNode) => void-1.0.0
onContextMenuCallback function when right click on an item(e: MouseEvent, node: TreeNode) => void-0.35.0
onSearchCallback function when the values for search input changes(sunInput: string) => void--
onSelectCallback function when selected, return the key property of data(selectedKey:string, selected: bool, selectedNode: TreeNode) => void--

TreeNode

Key for TreeNode is required and must be unique, label can be duplicated. Before v>=1.7.0 value is also required and must be unique. After v>=1.7.0, value is not required. In this case, the value property in onChange, value, defaultValue and onChangeWithObject will point to key property. To ensure everything behave as expected, keep a consistency of whether to have value or not to have value.
PropertiesInstructionsTypeDefault
valueValuestring|number-
labelDisplayed labelstring|ReactNode-
iconIconReactNode-
disabledDisabledbooleanfalse
keyRequired and must be uniquestring-
isLeafToggle whether node is leaf node, only takes effect in async load data with loadData v>=1.0.0boolean-

Virtualize Object

itemSize is required to render virtualized tree。
PropertiesInstructionsTypeDefault
heightHeight. If passed as a string, computed height should not be 0 for render purpose, in other words, parent node should have offsetHeightnumber|string'100%'
itemSizeHeight for each line of treeNode, requirednumber-
widthWidthnumber|string'100%'

Methods

NameDescriptionTypeVersion
searchTrigger search manually(value: string) => void-
scrollToIn a virtualized Tree, make the specified node(Which is an expanded node in the tree) scroll to view({key: string; align?: 'center' | 'start' | 'end' | 'smart' | 'auto';}) => void2.18.0

Accessibility

ARIA

  • Tree supports passing in aria-label to indicate the role of the Tree;
  • Tree will set aria-disabled, aria-checked, aria-selected, and aria-level for each child node to indicate the node status and level;
  • Tree will set role to tree and treeitem for corresponding parts.
Demo:

Content Guidelines

  • Try to use phrases, capitalize the first letter
  • Keep the same form of terminology between levels, such as all place names or country names

Design Tokens

© 2021 - 2022 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED