React Tree Select Component

5.27.0 verified Sat Apr 25 auth: no javascript

rc-tree-select is a highly customizable React UI component designed for selecting single or multiple items from a hierarchical tree structure. As part of the `react-component` ecosystem, it prioritizes unstyled, highly performant, and accessible base functionality, giving developers full control over styling and integration into custom design systems. The current stable version is `5.27.0`. While it maintains a consistent release cadence, the project has also seen the introduction of a scoped package, `@rc-component/tree-select` (currently around v1.x), which represents an ongoing evolution of the component and may introduce new features or a migration path for future consumers. Its primary differentiator is its "headless" nature, providing foundational logic without imposing visual styles, making it extremely flexible for diverse application needs.

Common errors

error Cannot resolve module 'rc-tree-select/assets/index.less' (or '.css') ↓

cause The component's default styles are not being imported or are incorrectly referenced. This often happens if a CSS/Less loader is not configured in the build system or the import path is wrong.

fix

Ensure you have a CSS/Less loader configured in your webpack/Vite setup. Add import 'rc-tree-select/assets/index.less'; (or index.css) to your main application entry point or the component where TreeSelect is used. For Vite, you might need specific alias configurations if encountering resolution issues.

error TypeError: Cannot read properties of undefined (reading 'map') (or similar errors related to data processing) ↓

cause The `treeData` prop (or children `TreeNode` components) is provided in an incorrect format or is `undefined`/`null`, leading to a runtime error when `rc-tree-select` attempts to process it.

fix

Verify that your treeData array conforms to the expected structure (an array of objects with value, label, and optional children). Ensure the data is not undefined or null before passing it to the TreeSelect component.

error Error: `value` prop on `TreeSelect` did not match a previous value. A common cause is when a consumer passes an inline array or object as a `value` prop. Consider providing a stable value. ↓

cause This React warning indicates that the `value` prop passed to `TreeSelect` is changing on every render, even if the selected value itself hasn't conceptually changed. This typically happens when a new array or object instance is created directly within the render function for a controlled component's `value`.

fix

Ensure that the value prop for TreeSelect (and other controlled props like expandedKeys) is derived from a stable state variable (e.g., using useState or useReducer) and is not being recreated as a new object/array instance on every render. Use JSON.stringify() or a stable reference for comparing complex value types.

error TreeSelect dropdown does not open or appears unstyled/misplaced. ↓

cause This is typically caused by missing or incorrect CSS imports, `z-index` conflicts with other elements on the page, or issues with the `dropdownStyle` or `dropdownClassName` props preventing proper rendering.

fix

First, ensure import 'rc-tree-select/assets/index.less'; (or .css) is correctly applied. Check for z-index conflicts, making sure the TreeSelect dropdown has a higher z-index than surrounding elements. Inspect the rendered DOM for any unexpected styles overriding rc-tree-select's dropdown styles. Adjust dropdownStyle for positioning if necessary.

Warnings

breaking Major version upgrades (e.g., v4 to v5) in `rc-tree-select` or related `rc-component` libraries frequently introduce breaking API changes, particularly around prop definitions, event handler signatures, or internal data structures. Always review the specific changelog for the version you are upgrading to. ↓

fix Consult the `rc-tree-select` or `react-component/tree-select` GitHub repository's changelog or releases section for detailed migration guides specific to your upgrade path. Pay close attention to changes in `value`, `onChange`, and `treeData` props.

gotcha `rc-tree-select` is an unstyled component. It provides the core logic and structure but does not include any default visual styling beyond minimal functional CSS. Developers must import `rc-tree-select/assets/index.css` (or `.less` if using a preprocessor) and then apply their own custom CSS or integrate it into a UI framework's styling system to make it visually presentable.

gotcha Performance can degrade significantly with very large datasets (e.g., thousands of tree nodes) if not properly managed. Avoid rendering deeply nested or excessively numerous nodes simultaneously. Consider using features like `treeDefaultExpandAll={false}`, virtualization, or server-side data loading/filtering for optimal performance. Using `treeCheckStrictly` can also impact performance in `checkable` mode.

deprecated While `TreeNode` components can be passed as direct children to `TreeSelect`, the documentation often recommends using the `treeData` prop instead. Using `treeData` typically offers better performance, easier data management, and cleaner code, especially for dynamic or large tree structures. ↓

fix Refactor your tree structure to be defined as an array of objects for the `treeData` prop, rather than nested `TreeNode` JSX elements. This also allows for easier integration with remote data sources.

gotcha There can be confusion between `rc-tree-select` and the newer `@rc-component/tree-select` scoped package. While `rc-tree-select` (v5.x) is the package requested, the `react-component` organization actively develops `@rc-component/tree-select` (v1.x) which may reflect future evolutions or different API considerations. Always verify the package name and version you intend to use. ↓

fix Explicitly define `rc-tree-select` in your `package.json` to ensure you are installing the intended version. For new projects, evaluate if `@rc-component/tree-select` offers a more modern API or features relevant to your needs, understanding it might represent a separate codebase or migration path.

Install

npm install rc-tree-select

yarn add rc-tree-select

pnpm add rc-tree-select

Imports

TreeSelect
wrong
```
import TreeSelect from 'rc-tree-select';
```
correct
```
import { TreeSelect } from 'rc-tree-select';
```
The primary component is a named export. Default imports will not work.
TreeNode
wrong
```
import TreeNode from 'rc-tree-select/lib/TreeNode';
```
correct
```
import { TreeSelect, TreeNode } from 'rc-tree-select';
```
TreeNode is a named export of the main package. Note that using the `treeData` prop is generally recommended over direct JSX `TreeNode` children for performance and easier management with large datasets.
TreeSelectProps
wrong
```
import { TreeSelectProps } from 'rc-tree-select';
```
correct
```
import type { TreeSelectProps } from 'rc-tree-select';
```
Importing types requires the `type` keyword in TypeScript for clarity and bundler optimization.

Quickstart

This example demonstrates a basic controlled `TreeSelect` component in a React functional component using TypeScript. It includes `treeData` for defining the hierarchical options, `useState` to manage the selected value, and an `onChange` handler to update it. It also shows importing essential styles.

import React, { useState } from 'react';
import { TreeSelect } from 'rc-tree-select';
import 'rc-tree-select/assets/index.less'; // Or index.css for basic styles, though custom styling is common.

interface TreeDataItem {
  value: string;
  label: string;
  children?: TreeDataItem[];
}

const treeData: TreeDataItem[] = [
  {
    value: 'parent 1',
    label: 'Parent 1',
    children: [
      {
        value: 'parent 1-0',
        label: 'Parent 1-0',
        children: [
          { value: 'leaf 1', label: 'Leaf 1' },
          { value: 'leaf 2', label: 'Leaf 2' },
        ],
      },
      { value: 'parent 1-1', label: 'Parent 1-1' },
    ],
  },
  { value: 'parent 2', label: 'Parent 2' },
];

const MyTreeSelectComponent: React.FC = () => {
  const [value, setValue] = useState<string | string[] | undefined>(undefined);

  const onChange = (newValue: string | string[] | undefined) => {
    console.log('Selected:', newValue);
    setValue(newValue);
  };

  return (
    <div style={{ width: 300, margin: '50px auto' }}>
      <h3>Basic TreeSelect Example</h3>
      <TreeSelect
        style={{ width: '100%' }}
        value={value}
        treeData={treeData}
        placeholder="Please select"
        onChange={onChange}
        allowClear
        showSearch
        treeDefaultExpandAll
      />
      <p>Selected Value: {JSON.stringify(value)}</p>
    </div>
  );
};

export default MyTreeSelectComponent;