{"id":18055,"library":"rc-tree-select","title":"React Tree Select Component","description":"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.","status":"active","version":"5.27.0","language":"javascript","source_language":"en","source_url":"https://github.com/react-component/tree-select","tags":["javascript","react","react-component","react-tree-select","tree-select","typescript"],"install":[{"cmd":"npm install rc-tree-select","lang":"bash","label":"npm"},{"cmd":"yarn add rc-tree-select","lang":"bash","label":"yarn"},{"cmd":"pnpm add rc-tree-select","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components to the DOM.","package":"react-dom","optional":false},{"reason":"Internal dependency for underlying select logic (implicit for v5.x and explicit in @rc-component/tree-select changelog).","package":"@rc-component/select","optional":false},{"reason":"Internal dependency for underlying tree structure logic (implicit for v5.x and explicit in @rc-component/tree-select changelog).","package":"@rc-component/tree","optional":false}],"imports":[{"note":"The primary component is a named export. Default imports will not work.","wrong":"import TreeSelect from 'rc-tree-select';","symbol":"TreeSelect","correct":"import { TreeSelect } from 'rc-tree-select';"},{"note":"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.","wrong":"import TreeNode from 'rc-tree-select/lib/TreeNode';","symbol":"TreeNode","correct":"import { TreeSelect, TreeNode } from 'rc-tree-select';"},{"note":"Importing types requires the `type` keyword in TypeScript for clarity and bundler optimization.","wrong":"import { TreeSelectProps } from 'rc-tree-select';","symbol":"TreeSelectProps","correct":"import type { TreeSelectProps } from 'rc-tree-select';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { TreeSelect } from 'rc-tree-select';\nimport 'rc-tree-select/assets/index.less'; // Or index.css for basic styles, though custom styling is common.\n\ninterface TreeDataItem {\n value: string;\n label: string;\n children?: TreeDataItem[];\n}\n\nconst treeData: TreeDataItem[] = [\n {\n value: 'parent 1',\n label: 'Parent 1',\n children: [\n {\n value: 'parent 1-0',\n label: 'Parent 1-0',\n children: [\n { value: 'leaf 1', label: 'Leaf 1' },\n { value: 'leaf 2', label: 'Leaf 2' },\n ],\n },\n { value: 'parent 1-1', label: 'Parent 1-1' },\n ],\n },\n { value: 'parent 2', label: 'Parent 2' },\n];\n\nconst MyTreeSelectComponent: React.FC = () => {\n const [value, setValue] = useState(undefined);\n\n const onChange = (newValue: string | string[] | undefined) => {\n console.log('Selected:', newValue);\n setValue(newValue);\n };\n\n return (\n
\n

Basic TreeSelect Example

\n \n

Selected Value: {JSON.stringify(value)}

\n
\n );\n};\n\nexport default MyTreeSelectComponent;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0"},{"message":"`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.","severity":"gotcha"},{"message":"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.","severity":"gotcha"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","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.","error":"Cannot resolve module 'rc-tree-select/assets/index.less' (or '.css')"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'map') (or similar errors related to data processing)"},{"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.","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`.","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."},{"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.","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.","error":"TreeSelect dropdown does not open or appears unstyled/misplaced."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}