Input · TreeSelect
TreeSelect
TreeSelector is used for structured display & selection of multi-level tree data, such as displaying a list of folders and files, displaying a list of organizational structure members, and so on.

When to Use

When the options to select is in tree structure, you could use TreeSelect, e.g. department hierarchy, subject system, category directory and etc.

Demos

How to import

Basic Usage

By default, TreeSelect 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.
Use leafOnly (>= v0.32.0) if you prefer to render leaf nodes only and the corresponding params for onChange will also be leaf nodes values.

Limit Tags Number

In the multi-selection scenario, maxTagCount can be used to limit the number of tags displayed, and the excess part will be displayed in the form of +N.
Use showRestTagsPopover (>= v2.22.0) to set whether hover +N displays Popover after exceeding maxTagCount, the default is false. Also, popovers can be configured in the restTagsPopoverProps property.

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.

Search Box Position

You can use searchPosition to set the position of the search box, optional: dropdown (default), trigger.
When the input box is at trigger:
  1. The placeholder of the search box is controlled by placeholder;
  2. When showClear=true, click the clear button of the input box, the inputValue and value will be cleared at the same time.

Size

You can set the size by size, one of: 'small'、'default'、'large'

Disabled

Disable Strictly

version: >= 1.30.0
You can use disableStrictly 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.
Take the following demo as an example, the node "China" is strictly disabled. Therefore, when we change the selected state of its parent node "Asia", it will not affect the selected state of the node "China".

Default Expand All

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

Controlled Component

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

Checked RelationShip

Version: >= 2.5.0
In multiple, 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.
When expandedKeys is passed in, it is a controlled expansion component, which can be used with onExpand. When the expansion is controlled, if the filterTreeNode is turned on and the search is performed, the node will no longer be automatically expanded. At this time, the expansion of the node is completely controlled by the expandedKeys. You can use the parameter filteredExpandedKeys (version: >= 2.6.0) of onSearch to realize the search expansion effect when the expansion is controlled.

Virtualized TreeSelect

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 dropDown, If passed in as a string, computed height should not be zero for render purpose, in other words, parent node should have offsetHeight. Pass in a number recommended.
  • width: Width of the dropDown.
  • 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.

Custom Trigger

If the default trigger style cannot meet your needs, you can use triggerRender to customize the display of the select box.
The triggerRender input is as follows:

Custom Rendering Selected Item

You can use renderSelectedItem to customize the rendering structure of the selected item in the selection box.
  • In not multiple mode: renderSelectedItem(treeNode: TreeNodeData) => content: ReactNode
  • In multiple mode: renderSelectedItem(treeNode: TreeNodeData, { index:number, onClose:function }) => { isRenderInTag: bool, content: ReactNode }
    • When isRenderInTag is true, content wraps are automatically rendered in the Tag (with background color and close button)
    • When isRenderInTag is false, the returned content will be rendered directly

API Reference

TreeSelect

PropertiesInstructionstypeDefaultVersion
arrowIconCustomize the right drop-down arrow Icon, when the showClear switch is turned on and there is currently a selected value, hover will give priority to the clear iconReactNode1.15.0
autoAdjustOverflowWhether the pop-up layer automatically adjusts the direction when it is obscured (only vertical direction is supported for the time being, and the inserted parent is body)booleantrue0.34.0
autoExpandParentToggle whether to expand parent nodes automaticallybooleanfalse0.34.0
borderlessborderless mode >=2.33.0boolean
checkRelationIn multiple, the relationship between the checked states of the nodes, optional: 'related'、'unRelated'string'related'2.5.0
classNameClass namestring--
clearIconCan be used to customize the clear button, valid when showClear is trueReactNode2.25.0
clickToHideWhether to close the drop-down layer automatically when selecting, only works in single-selection modebooleantrue1.5.0
clickTriggerToHideWhen the panel is open, whether to close the panel after clicking the Triggerbooleantrue2.32.0
defaultExpandAllSet whether to expand all nodes during initialization. And if the data (treeData) changes, this api cannot affect the expansion of the node. If you need this, you can use expandAllbooleanfalse0.32.0
defaultExpandedKeysKeys of default expanded nodes. Direct child nodes will be displayed.string[]-0.32.0
defaultOpenToggle whether to open dropdown menu by defaultbooleanfalse0.32.0
defaultValueDefault value
ValueType
--
disabledDisabledbooleanfalse-
disableStrictlyDisable Strictlybooleanfalse1.30.0
dropdownClassNameclassName property for dropDownstring--
dropdownMatchSelectWidthToggle if min-width of dropDown menu should be same as width of select boxbooleantrue-
dropdownMarginPopup layer calculates the size of the safe area when the current direction overflows, used in scenes covered by fixed elements, more detail refer to issue#549, same as Tooltip marginobject|number2.25.0
dropdownStyleStyle for dropDownCSSProperties--
emptyContentEmpty content when no dataReactNodeno result-
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 | stringfalse1.4.0
expandAllSet whether to expand all nodes by default. If the data (treeData) changes, the default expansion will still be affected by this apibooleanfalse1.30.0
expandedKeys(Controlled)Keys of expanded nodes. Direct child nodes will be displayed.string[]-0.32.0
keyMapsCustomize the key, label, and value fields in the nodeobject-2.47.0
filterTreeNodeToggle whether searchable or pass in a function to customize search behavior, data parameter provided since v2.28.0boolean|(inputValue: string, treeNodeString: TreeNodeString, data?: TreeNodeData) => booleanfalse-
getPopupContainerContainer to render pop-up, you need to set 'position: relative` This will change the DOM tree position, but not the view's rendering position.function():HTMLElement--
insetLabelPrefix alias,used mainly in FormReactNode-0.28.0
labelEllipsisToggle whether to ellipsis label when overflowbooleanfalse|true(virtualized)1.8.0
leafOnlyToggle whether to display tags for leaf nodes only and for onChange callback params in multiple modebooleanfalse0.32.0
loadDataLoad data asynchronously and the return value should be a promise(treeNode: TreeNodeData) => Promise-1.32.0
loadedKeys(Controlled)Mark node as loaded, working with loadDataSet< string >-1.32.0
maxTagCountMaximum number of tags displayednumber--
motionExpandToggle whether to turn on animation for expansionbooleantrue-
multipleToggle whether in multi-choice modebooleanfalse-
optionListStyleStyle for optionListCSSProperties-1.8.0
outerBottomSlotRendered at the bottom of the pop-up layer, custom slot level with optionListReactNode-1.1.0
outerTopSlotRendered at the top of the pop-up layer, custom slot level with optionList. If turn on filterTreeNode, it will replace search box as well. You could use static search method to customize instead.ReactNode-1.9.0
placeholderPlaceholder for input boxstring--
positionPop-up position, optional values refer to Tooltip positionstringbottomLeft2.25.0
prefixPrefixReactNode-0.28.0
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
renderFullLabelCustom option render function, Detailed Params and Usage(obj) => ReactNode1.7.0
renderLabelCustom label render function
(label, data) => ReactNode
1.6.0
renderSelectedItemrender selected itemFunction-1.26.0
restTagsPopoverPropsThe configuration properties of the PopoverPopoverProps{}2.22.0
searchAutoFocusWhether autofocus for search boxbooleanfalse1.27.0
searchPlaceholderPlaceholder for search boxstring--
searchPositionSet the position of the search box, one of: dropdowntriggerstringdropdown1.29.0
showClearWhen the value is not empty, whether the trigger displays the clear buttonbooleanfalse
showFilteredOnlyToggle whether to displayed filtered result only in search modebooleanfalse0.32.0
showLineThe option in the options panel shows connecting linesbooleanfalse2.50.0
showRestTagsPopoverWhen the number of tags exceeds maxTagCount and hover reaches +N, whether to display the remaining content through Popoverbooleanfalse2.22.0
showSearchClearToggle whether to support clear search boxbooleantrue0.35.0
sizeSize for input box,one of largesmalldefaultstringdefault-
styleInline styleCSSProperties--
suffixSuffixReactNode-0.28.0
treeDataData for treeNodesTreeNodeData[][]-
treeNodeFilterPropProperty in a TreeNodeData used to searchstringlabel-
treeNodeLabelPropProperty in a TreeNodeData used to displaystringlabel-
triggerRenderMethod to create a custom trigger(props: TriggerRenderProps) => ReactNode-0.34.0
validateStatusValidate status,one of warningerrordefault, only affects the background color of the componentstring-0.32.0
valueValue data of current item, used when TreeSelect is a controlled component
ValueType
--
virtualizeEfficiently rendering large lists, refer to Tree - VirtualizeObj. Motion is disabled when tree is rendered as virtualized list.object-0.32.0
zIndexzIndex for treeSelect dropDown menunumber10300.30.0
onBlurCallback function when treeSelect blurfunction(event)--
onFocusCallback function when treeSelect focusfunction(event)--
onChangeCallback function when the tree node is selected, return the value property of dataFunction--
onChangeWithObjectToggle whether to return all properties in an option as a return value. When set to true, onChange turn to Function(node, e)booleanfalse1.0.0
onClearCallback triggered when clear button is clicked(e: Event) => void-2.52.0
onExpandCallback function when expand or collapse a node
(expandedKeys, object) => void
--
onLoadCallback function when a node is loaded
(loadedKeys, treeNode) => void
-1.32.0
onSearchCallback function when search value changes. filteredExpandedKeys represents the key of the node expanded due to search or value/defaultValue, which can be used when expandedKeys is controlled
filteredExpandedKeys is supported in 2.6.0
function(input: string, filteredExpandedKeys: string[])-
onSelectCallback function when selected, return the key property of datafunction(selectedKey:string, selected: bool, selectedNode: TreeNodeData)--
onVisibleChangeA callback triggered when the pop-up layer is displayed/hiddenfunction(isVisible:boolean)1.4.0

TreeNodeData

Key for TreeNodeData 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-
disabledDisabled, supported in multiple select modebooleanfalse
keyRequired and must be uniquestring-
isLeafWhether it is a leaf nodeboolean-

Methods

Some internal methods provided by TreeSelect can be accessed through ref:
NameDescription
search(sugInput: string)If you need to customize the search box externally, you can actively call this method when the value of the custom search box changes to change the filtering results

Accessibility

ARIA

  • TreeSelect will automatically set aria-label to 'TreeSelect', and also support users to set aria-label to indicate the function of the TreeSelect;
  • TreeSelect allows users to set aria-describedby, aria-errormessage, aria-invalid, aria-labelledby, aria-required, in addition, Form will automatically set these properties for Form.TreeSelect;
  • TreeSelect will set aria-disabled, aria-checked, aria-selected, aria-level for each child node to indicate node status and level;
Demo:

Design Tokens