# TreeSelect

- Page: https://jiguang132.com/resources/ant-design/docs/tree-select
- Resource: Ant Design (https://jiguang132.com/resources/ant-design.md)
- All guides: https://jiguang132.com/resources/ant-design/docs.md

Tree selection control.


## When To Use

`TreeSelect` is similar to `Select`, but the values are provided in a tree like structure. Any data whose entries are defined in a hierarchical manner is fit to use this control. Examples of such case may include a corporate hierarchy, a directory structure, and so on.

## Examples


- Basic · `basic`
- Multiple Selection · `multiple`
- Generate from tree data · `treeData`
- Checkable · `checkable`
- Asynchronous loading · `async`
- Show Tree Line · `treeLine`
- Placement · `placement`
- Variants · `variant`
- Status · `status`
- Max Count · `maxCount`
- Prefix and Suffix · `suffix`
- Custom semantic dom styling · `style-class`



## API

Common props ref：[Common props](#jguang-common-props)

### Tree props

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| allowClear | Customize clear icon | boolean \| { clearIcon?: ReactNode } | false | 5.8.0: Support object type | × |
| ~~autoClearSearchValue~~ | If auto clear search input value when multiple select is selected/deselected | boolean | true |  | × |
| ~~bordered~~ | Whether has border style, please use `variant` instead | boolean | true | - | × |
| classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  | 5.25.0 |
| defaultOpen | Initial open state of dropdown | boolean | - |  | × |
| defaultValue | To set the initial selected treeNode(s) | string \| string\[] | - |  | × |
| disabled | Disabled or not | boolean | false |  | × |
| ~~dropdownClassName~~ | The className of dropdown menu, please use `classNames.popup.root` instead | string | - | - | × |
| ~~dropdownMatchSelectWidth~~ | Determine whether the popup menu and the select input are the same width, please use `popupMatchSelectWidth` instead | boolean \| number | true | - | × |
| ~~popupClassName~~ | The className of dropdown menu, use `classNames.popup.root` instead | string | - | 4.23.0 | × |
| popupMatchSelectWidth | Determine whether the popup menu and the select input are the same width. Default set `min-width` same as input. Will ignore when value less than select width. `false` will disable virtual scroll | boolean \| number | true | 5.5.0 | × |
| ~~dropdownRender~~ | Customize dropdown content, use `popupRender` instead | (originNode: ReactElement) => ReactNode | - |  | × |
| popupRender | Customize dropdown content | (originNode: ReactElement) => ReactNode | - |  | × |
| ~~dropdownStyle~~ | To set the style of the dropdown menu, use `styles.popup.root` instead | CSSProperties | - |  | × |
| fieldNames | Customize node label, value, children field name | object | { label: `label`, value: `value`, children: `children` } | 4.17.0 | × |
| ~~filterTreeNode~~ | Whether to filter treeNodes by input value. The value of `treeNodeFilterProp` is used for filtering by default | boolean \| function(inputValue: string, treeNode: TreeNode) (should return boolean) | function |  | × |
| getPopupContainer | To set the container of the dropdown menu. The default is to create a `div` element in `body`, you can reset it to the scrolling area and make a relative reposition. [example](https://codepen.io/afc163/pen/zEjNOy?editors=0010) | function(triggerNode) | () => document.body |  | × |
| labelInValue | Whether to embed label in value, turn the format of value from `string` to {value: string, label: ReactNode, halfChecked: boolean (Is the option list in a semi selected state and not displayed in the values)} | boolean | false |  | × |
| listHeight | Config popup height | number | 256 |  | × |
| loadData | Load data asynchronously. Will not load when filtering. Check FAQ for more info | function(node) | - |  | × |
| maxCount | The maximum number of items that can be selected. Only takes effect when `multiple=true`. If (`showCheckedStrategy = 'SHOW_ALL'` and `treeCheckStrictly` is disabled) or `showCheckedStrategy = 'SHOW_PARENT'` is used, `maxCount` will not take effect. | number | - | 5.23.0 | × |
| maxTagCount | Max tag count to show. `responsive` will cost render performance | number \| `responsive` | - | responsive: 4.10 | × |
| maxTagPlaceholder | Placeholder for not showing tags | ReactNode \| function(omittedValues) | - |  | × |
| maxTagTextLength | Max tag text length to show | number | - |  | × |
| multiple | Support multiple or not, will be `true` when enable `treeCheckable` | boolean | false |  | × |
| notFoundContent | Specify content to show when no result matches | ReactNode | `No data` |  | × |
| open | Controlled open state of dropdown | boolean | - |  | × |
| placeholder | Placeholder of the select input | string | - |  | × |
| placement | The position where the selection box pops up | `bottomLeft` `bottomRight` `topLeft` `topRight` | bottomLeft |  | × |
| prefix | The custom prefix | ReactNode | - | 5.22.0 | × |
| ~~searchValue~~ | Work with `onSearch` to make search value controlled | string | - |  | × |
| ~~showArrow~~ | Whether to show the arrow icon, please use `suffixIcon={null}` instead | boolean | true | - | × |
| showCheckedStrategy | The way show selected item in box when `treeCheckable` set. **Default:** just show child nodes. **`TreeSelect.SHOW_ALL`:** show all checked treeNodes (include parent treeNode). **`TreeSelect.SHOW_PARENT`:** show checked treeNodes (just show parent treeNode) | `TreeSelect.SHOW_ALL` \| `TreeSelect.SHOW_PARENT` \| `TreeSelect.SHOW_CHILD` | `TreeSelect.SHOW_CHILD` |  | × |
| showSearch | Support search or not | boolean \| [Object](#showsearch) | single: false \| multiple: true |  | × |
| size | To set the size of the select input | `large` \| `medium` \| `small` | - |  | × |
| status | Set validation status | 'error' \| 'warning' | - | 4.19.0 | × |
| styles | Customize inline style for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - |  | 5.25.0 |
| suffixIcon | The custom suffix icon | ReactNode | `<DownOutlined />` |  | × |
| switcherIcon | Customize collapse/expand icon of tree node | ReactNode \| ((props: AntTreeNodeProps) => ReactNode) | - | renderProps: 4.20.0 | 5.28.0 |
| tagRender | Customize tag render when `multiple` | (props) => ReactNode | - |  | × |
| treeCheckable | Whether to show checkbox on the treeNodes | boolean | false |  | × |
| treeCheckStrictly | Whether to check nodes precisely (in the `checkable` mode), means parent and child nodes are not associated, and it will make `labelInValue` be true | boolean | false |  | × |
| treeData | Data of the treeNodes, manual construction work is no longer needed if this property has been set(ensure the Uniqueness of each value) | array&lt;{ value, title, children, \[disabled, disableCheckbox, selectable, checkable] }> | \[] |  | × |
| treeDataSimpleMode | Enable simple mode of treeData. Changes the `treeData` schema to: \[{id:1, pId:0, value:'1', title:"test1",...},...] where pId is parent node's id). It is possible to replace the default `id` and `pId` keys by providing object to `treeDataSimpleMode` | boolean \| object&lt;{ id: string, pId: string, rootPId: string }> | false |  | × |
| treeDefaultExpandAll | Whether to expand all treeNodes by default | boolean | false |  | × |
| treeDefaultExpandedKeys | Default expanded treeNodes | string\[] | - |  | × |
| treeExpandAction | Tree title open logic when click, optional: false \| `click` \| `doubleClick` | string \| boolean | false | 4.21.0 | × |
| treeExpandedKeys | Set expanded keys | string\[] | - |  | × |
| treeIcon | Shows the icon before a TreeNode's title. There is no default style; you must set a custom style for it if set to `true` | boolean | false |  | × |
| treeLine | Show the line. Ref [Tree - showLine](/components/tree/#tree-demo-line) | boolean \| object | false | 4.17.0 | × |
| treeLoadedKeys | (Controlled) Set loaded tree nodes, work with `loadData` only | string[] | [] |  | × |
| ~~treeNodeFilterProp~~ | Will be used for filtering if `filterTreeNode` returns true | string | `value` |  | × |
| treeNodeLabelProp | Will render as content of select | string | `title` |  | × |
| treeTitleRender | Customize tree node title render | (nodeData) => ReactNode | - | 5.12.0 | × |
| value | To set the current selected treeNode(s) | string \| string\[] | - |  | × |
| variant | Variants of selector | `outlined` \| `borderless` \| `filled` \| `underlined` | `outlined` | 5.13.0 \| `underlined`: 5.24.0 | 5.19.0 |
| virtual | Disable virtual scroll when set to false | boolean | true | 4.1.0 | × |
| onChange | A callback function, can be executed when selected treeNodes or input value change | function(value, label, extra) | - |  | × |
| onClear | Called when clear | () => void | - | - | × |
| ~~onDropdownVisibleChange~~ | Called when dropdown open, use `onOpenChange` instead | function(open) | - |  | × |
| onOpenChange | Called when dropdown open | (open: boolean) => void | - |  | × |
| onPopupScroll | Called when dropdown scrolls | (event: UIEvent) => void | - | 5.17.0 | × |
| ~~onSearch~~ | A callback function, can be executed when the search input changes | function(value: string) | - |  | × |
| onSelect | A callback function, can be executed when you select a treeNode | function(value, node, extra) | - |  | × |
| onTreeExpand | A callback function, can be executed when treeNode expanded | function(expandedKeys) | - |  | × |

### showSearch

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| autoClearSearchValue | If auto clear search input value when multiple select is selected/deselected | boolean | true |  |
| filterTreeNode | Whether to filter treeNodes by input value. The value of `treeNodeFilterProp` is used for filtering by default | boolean \| function(inputValue: string, treeNode: TreeNode) (should return boolean) | function |  |
| searchValue | Work with `onSearch` to make search value controlled | string | - |  |
| treeNodeFilterProp | Will be used for filtering if `filterTreeNode` returns true | string | `value` |  |
| onSearch | A callback function, can be executed when the search input changes | function(value: string) | - |  |

### Tree Methods

| Name    | Description  | Version |
| ------- | ------------ | ------- |
| blur()  | Remove focus |         |
| focus() | Get focus    |         |

### TreeNode props

> We recommend you to use `treeData` rather than `TreeNode`, to avoid the trouble of manual construction.

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| checkable | When Tree is checkable, set TreeNode display Checkbox or not | boolean | - |  |
| disableCheckbox | Disables the checkbox of the treeNode | boolean | false |  |
| disabled | Disabled or not | boolean | false |  |
| isLeaf | Leaf node or not | boolean | false |  |
| key | Required property (unless using `treeDataSimpleMode`), should be unique in the tree | string | - |  |
| selectable | Whether can be selected | boolean | true |  |
| title | Content showed on the treeNodes | ReactNode | `---` |  |
| value | Will be treated as `treeNodeFilterProp` by default, should be unique in the tree | string | - |  |

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `root` | Root element with tree selector base styles, border, border radius container styles | — |
| `prefix` | Prefix element with prefix content layout and styles | — |
| `placeholder` | Placeholder element with font styles and colors for placeholder text | — |
| `input` | Input element with text input, search, selected value display and other input core interaction styles | — |
| `suffix` | Suffix element with suffix content, clear button, dropdown arrow and other suffix area styles | — |
| `popup.root` | Popup element with dropdown tree selection panel positioning, z-index, background, border, shadow and other popup layer styles | — |
| `popup.item` | Popup item element with tree node option styles, hover state, selected state and other interaction states | — |
| `popup.itemTitle` | Popup title element with tree node title text display styles | — |
| `popup.itemSwitcher` | Popup switcher element with tree node expand/collapse button styles and background | 6.4.0 |
| `content` | Multiple selection container with layout, spacing, and wrapping styles for selected items (multiple) | — |
| `item` | Multiple selection item element with border, background, padding, and margin styles (multiple) | — |
| `itemContent` | Multiple selection item content area with text ellipsis styles (multiple) | — |
| `itemRemove` | Multiple selection item remove button with font-related styles (multiple) | — |

Semantic description source: `vendor/.dumi/theme/common/TreeSelectSemanticTemplate.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.

Native ComponentToken declares no directly extractable own fields. Shared tokens and inheritance are defined by the declarations below.

Declaration source: `vendor/components/tree-select/style/index.ts`

```ts
import { unit } from '@ant-design/cssinjs';

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

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

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

import type { TreeSharedToken } from '../../tree/style';

import { genTreeStyle, initComponentToken } from '../../tree/style';

export interface ComponentToken extends TreeSharedToken {}

interface TreeSelectToken extends FullToken<'TreeSelect'> {
  treePrefixCls: string;
}
```

## FAQ

### How to get parent node in onChange? {#faq-parent-node-info}

We don't provide this since performance consideration. You can get by this way: <https://codesandbox.io/s/get-parent-node-in-onchange-eb1608>

### Why sometimes customize Option cause scroll break? {#faq-custom-option-scroll}

You can ref Select [FAQ](/components/select).

### Why `loadData` not trigger when searching? {#faq-load-data-expand}

In earlier version, `loadData` will be triggered when searching. But we got feedback that it will block network when inputting. So we change it to not trigger `loadData` when searching. But you can still handle async logic by `filterTreeNode`:

```tsx
<TreeSelect
  filterTreeNode={(input, treeNode) => {
    const match = YOUR_LOGIC_HERE;

    if (match && !treeNode.isLeaf && !treeNode.children) {
      // Do some loading logic
    }

    return match;
  }}
/>
```

### Why can't popup scroll horizontally? {#faq-popup-not-scroll}

Just turn off virtual scrolling, because the `scrollWidth` of the complete list cannot be accurately measured when virtual scrolling is turned on.


## Shared native props {#jguang-common-props}


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

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
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-select/index.tsx`
- `vendor/components/tree-select/style/index.ts`

## 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.

---

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