Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TreeSelect
✓ import { TreeSelect } from 'rc-tree-select';
✗ import TreeSelect from 'rc-tree-select';
The primary component is a named export. Default imports will not work.
TreeNode
✓ import { TreeSelect, TreeNode } from 'rc-tree-select';
✗ import TreeNode from 'rc-tree-select/lib/TreeNode';
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
✓ import type { TreeSelectProps } from 'rc-tree-select';
✗ import { TreeSelectProps } from 'rc-tree-select';
Importing types requires the `type` keyword in TypeScript for clarity and bundler optimization.
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;
Debug
Known issues
breakingMajor 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.fixConsult 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.
affects: >=4.0
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.
gotchaPerformance 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.
deprecatedWhile `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.fixRefactor 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.
affects: >=3.0
gotchaThere 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.fixExplicitly 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.
affects: All versions
Errors
Common errors & fixes
Cannot resolve module 'rc-tree-select/assets/index.less' (or '.css')
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.
fixEnsure 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.
TypeError: Cannot read properties of undefined (reading 'map') (or similar errors related to data processing)
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.
fixVerify 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: `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.
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`.
fixEnsure 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.
TreeSelect dropdown does not open or appears unstyled/misplaced.
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.
fixFirst, 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.
Audit
Dependencies
reactrequiredPeer dependency for React applications.
react-domrequiredPeer dependency for rendering React components to the DOM.
@rc-component/selectrequiredInternal dependency for underlying select logic (implicit for v5.x and explicit in @rc-component/tree-select changelog).
@rc-component/treerequiredInternal dependency for underlying tree structure logic (implicit for v5.x and explicit in @rc-component/tree-select changelog).