Tree

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.

import { NzTreeModule } from 'ng-zorro-antd/tree';

Examples

parent 1parent 1-0leaf 1-0-0leaf 1-0-1parent 1-1

The most basic usage, tell you how to use checkable, selectable, disabled, defaultExpandKeys, and etc.

expand codeexpand code
      Loading...
    
0-00-0-00-0-0-00-0-0-10-0-0-20-0-10-0-20-10-2

Drag treeNode to insert after the other treeNode or insert into the other parent TreeNode.

expand codeexpand code
      Loading...
    
Expand to loadExpand to loadTree Node

To load data asynchronously when click to expand a treeNode.

expand codeexpand code
      Loading...
    
parent 1parent 1-0leafleafleafparent 1-1parent 1-2

Tree With Line.

expand codeexpand code
      Loading...
    
parent 0created by ng zorroleaf 0-0modified by ng zorroleaf 0-1modified by ng zorroparent 1created by ng zorro

Customize directory tree with nzTreeTemplate, get data from let-origin="origin", get node status from let-node.

expand codeexpand code
      Loading...
    
0-00-0-00-0-0-00-0-0-10-0-0-20-0-10-0-1-00-0-1-10-0-1-20-0-20-10-2

basic controlled example.

expand codeexpand code
      Loading...
    
0-00-0-00-0-1

nzBeforeDrop: Validate before drop event, for example: only allow to drag inside(delay 1s)、 validate using modal .etc.

expand codeexpand code
      Loading...
    
parent 1leafleaf
parent 1leafleaf

You can customize icons for different nodes.

expand codeexpand code
      Loading...
    

Set nzVirtualHeight to enable virtual scroll.

expand codeexpand code
      Loading...
    

API#

nz-tree#

Tips: According to the current data structure design, you need to ensure that nzData is set first, otherwise other attributes will not take effect. After the asynchronous operation returns data, re-assign other attributes to trigger rendering(including nzExpandAllnzExpandedKeysnzCheckedKeysnzSelectedKeysnzSearchValue). Please refer to #5152 to track the optimization progress.

PropertyDescriptionTypeDefaultGlobal Config
[nzData]Tree data (Reference NzTreeNode)NzTreeNodeOptions[] | NzTreeNode[][]
[nzBlockNode]Whether treeNode fill remaining horizontal spacebooleanfalse
[nzCheckable]Add a checkbox before the treeNodesbooleanfalse
[nzShowExpand]Show a Expand Icon before the treeNodesbooleantrue
[nzShowLine]Shows a connecting linebooleanfalse
[nzExpandedIcon]Customize an expand iconTemplateRef<{ $implicit: NzTreeNode }>-
[nzShowIcon]Shows the icon before a TreeNode's title. There is no default stylebooleanfalse
[nzAsyncData]Load data asynchronously (should be used with NzTreeNode.addChildren(...))booleanfalse
[nzDraggable]Specifies whether this Tree is draggable (IE > 8)booleanfalse
[nzMultiple]Allows selecting multiple treeNodesbooleanfalse
[nzHideUnMatched]Hide unmatched nodes while searchingbooleanfalse
[nzCheckStrictly]Check treeNode precisely; parent treeNode and children treeNodes are not associatedbooleanfalse
[nzTreeTemplate]Custom NodesTemplateRef<{ $implicit: NzTreeNode }>-
[nzExpandAll]Whether to expand all treeNodesbooleanfalse
[nzExpandedKeys]Specify the keys of the default expanded treeNodesstring[][]
[nzCheckedKeys]Specifies the keys of the default checked treeNodesstring[][]
[nzSelectedKeys]Specifies the keys of the default selected treeNodesstring[][]
[nzSearchValue]Filter (highlight) treeNodes (see demo Searchable), two-way bindingstringnull
[nzSearchFunc]Custom matching method, used with nzSearchValue(node: NzTreeNodeOptions) => booleannull
[nzBeforeDrop]Drop before the second check, allowing the user to decide whether to allow placement(confirm: NzFormatBeforeDropEvent) => Observable<boolean>-
[nzVirtualHeight]The height of virtual scrollstring-
[nzVirtualItemSize]The size of the items in the list, same as cdk itemSizenumber28
[nzVirtualMaxBufferPx]The number of pixels worth of buffer to render for when rendering new items, same as cdk maxBufferPxnumber500
[nzVirtualMinBufferPx]The minimum amount of buffer rendered beyond the viewport (in pixels),same as cdk minBufferPxnumber28
(nzClick)Callback function for when the user clicks a treeNodeEventEmitter<NzFormatEmitEvent>-
(nzDblClick)Callback function for when the user double clicks a treeNodeEventEmitter<NzFormatEmitEvent>-
(nzContextMenu)Callback function for when the user right clicks a treeNodeEventEmitter<NzFormatEmitEvent>-
(nzCheckboxChange)Callback function for when user clicks the checkboxEventEmitter<NzFormatEmitEvent>-
(nzExpandChange)Callback function for when a treeNode is expanded or collapsedEventEmitter<NzFormatEmitEvent>-
(nzSearchValueChange)Callback function for when filter treeNodes(used with nzSearchValue)EventEmitter<NzFormatEmitEvent>-
(nzOnDragStart)Callback function for when the onDragStart event occursEventEmitter<NzFormatEmitEvent>-
(nzOnDragEnter)Callback function for when the onDragEnter event occursEventEmitter<NzFormatEmitEvent>-
(nzOnDragOver)Callback function for when the onDragOver event occursEventEmitter<NzFormatEmitEvent>-
(nzOnDragLeave)Callback function for when the onDragLeave event occursEventEmitter<NzFormatEmitEvent>-
(nzOnDrop)Callback function for when the onDrop event occursEventEmitter<NzFormatEmitEvent>-
(nzOnDragEnd)Callback function for when the onDragEnd event occursEventEmitter<NzFormatEmitEvent>-

Methods#

PropertyDescriptionType
getTreeNodesget all nodes(NzTreeNode)NzTreeNode[]
getTreeNodeByKeyget NzTreeNode with keyNzTreeNode
getCheckedNodeListget checked nodes(merged)NzTreeNode[]
getSelectedNodeListget selected nodesNzTreeNode[]
getHalfCheckedNodeListget half checked nodesNzTreeNode[]
getExpandedNodeListget expanded nodesNzTreeNode[]
getMatchedNodeListget matched nodes(if nzSearchValue is not null)NzTreeNode[]

NzTreeNodeOptions props#

PropertyDescriptionTypeDefault
titleTitlestring'---'
keyMust be unique!stringnull
iconicon before the treeNode,used with nzShowIconstringnull
childrenTreeNode's childrenNzTreeNodeOptions[][]
isLeafDetermines if this is a leaf node(can not be dropped to)booleanfalse
checkedSet the treeNode be checkedbooleanfalse
selectedSet the treeNode be selectedbooleanfalse
expandedSet the treeNode be expanded ()booleanfalse
selectableSet whether the treeNode can be selectedbooleantrue
disabledDisables the treeNodebooleanfalse
disableCheckboxDisables the checkbox of the treeNodebooleanfalse
[key: string]Indexable Types, can be used with NzTreeNode.originany -

NzFormatEmitEvent props#

PropertyDescriptionTypeDefault
eventNameEvent Nameenum: clickdblclickcontextmenucheckexpandsearch & dragstartdragenterdragoverdragleavedropdragend-
nodeThe current operation node (such as the target node to drop while dragging)NzTreeNodenull
eventMouseEvent or DragEvent'MouseEvent' | 'DragEvent'null
dragNode?Current drag node (existing if dragged)NzTreeNodenull
selectedKeys?Selected nodes listNzTreeNode[][]
checkedKeys?Checked nodes listNzTreeNode[][]
matchedKeys?Matched keys list while searchingNzTreeNode[][]
keys?All nodes' keys list related event(except drag events)string[][]
nodes?All nodes related event(except drag events)NzTreeNode[][]

NzFormatBeforeDropEvent props#

PropertyDescriptionTypeDefault
dragNodeCurrent drag node (existing when dragged)NzTreeNode-
nodeThe current operation node (such as the target node to drop while dragging)NzTreeNode-
posposition to drop(-1: before the target node, 0: inside the target node, 1: behind the target node)number-

NzTreeNode props#

PropertyDescriptionTypeDefault
titleTitlestringNzTreeNodeOptions.title
keyKeystringNzTreeNodeOptions.key
levelTreeNode's level relative to the root nodenumbernumber
childrenChildrenNzTreeNode[][]
origintreeNode's raw data of NzTreeNodeOptions(user provided to show more datas)NzTreeNodeOptions-
getParentNodeGet parentNodefunctionnull
isLeafWhether treeNode is a Leaf Nodebooleanfalse
isExpandedWhether treeNode is expandedbooleanfalse
isDisabledWhether treeNode is disabledbooleanfalse
isDisableCheckboxWhether treeNode's checkbox can not be clickedbooleanfalse
isSelectableSet whether the treeNode can be selectedbooleantrue
isCheckedWhether treeNode is checkedbooleanfalse
isHalfCheckedPart of treeNode's children are checkedbooleanfalse
isSelectedWhether treeNode is selectedbooleanfalse
isLoadingWhether treeNode is loading(when nzAsyncData is true)booleanfalse
isMatchedWhether treeNode's title contains nzSearchValuebooleanfalse
setSyncCheckedset isChecked value and sync other nodes' state of checkboxfunction-
getChildrenGet all childrenfunction-
addChildrenAdd child nodes, receive NzTreeNode or NzTreeNodeOptions array, the second parameter is the inserted index position(children: array, index?: number )=>{}-
clearChildrenClear the treeNode's childrenfunction-
removeClear current node(not root node)function-

Note#

  • Please make sure nzData is set before the mentioned properties above:
// Demo
this.nzExpandAll = false;
const nodes = []; // source data
this.nzData = [...nodes];
// Reset the above mentioned properties if you have used after setting of nzData
this.nzExpandedKeys = [...this.nzExpandedKeys];
// this.nzExpandAll = true;
this.nzCheckedKeys = [...this.nzCheckedKeys];
this.nzSelectedKeys = [...this.nzSelectedKeys];
  • NzTreeNodeOptions accepts your custom properties,use NzTreeNode.origin to get them.
  • If Tree Methods are used with ViewChild, should be used in ngAfterViewInit.
  • Setting nzData with NzTreeNodeOptions[] is better,if you set nzData with NzTreeNode[], it will be deprecated in next major version(8.x).