{"id":15171,"library":"rc-select","title":"React Headless Select Component","description":"rc-select is a foundational, unstyled React component designed for building highly customizable select input fields. It provides a robust set of core functionalities, including single and multiple selection modes, search capabilities, and comprehensive dropdown management, without dictating any specific UI or styling framework. The current stable version, as per npm metadata, is 14.16.8, though associated projects under `@rc-component/select` show frequent patch releases, indicating active development and maintenance primarily focused on bug fixes and stability. This library serves as a powerful primitive, famously underpinning the `Select` component within major UI libraries like Ant Design. Its key differentiator is its headless architecture, granting developers complete control over the rendering of internal elements and visual presentation, making it an excellent choice for applications requiring highly custom designs and strict adherence to accessibility standards.","status":"active","version":"14.16.8","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/react-component/select","tags":["javascript","react","react-component","react-select","select","typescript"],"install":[{"cmd":"npm install rc-select","lang":"bash","label":"npm"},{"cmd":"yarn add rc-select","lang":"bash","label":"yarn"},{"cmd":"pnpm add rc-select","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for rendering React components.","package":"react","optional":false},{"reason":"Peer dependency required for rendering React components to the DOM.","package":"react-dom","optional":false}],"imports":[{"note":"The primary default export for the Select component. While CommonJS `require` might work in some setups, ESM `import` is the recommended and modern approach for React projects.","wrong":"const Select = require('rc-select');","symbol":"Select","correct":"import Select from 'rc-select';"},{"note":"Option is a named export and must be destructured. It should only be used as a direct child of the Select component.","wrong":"const { Option } = require('rc-select');","symbol":"Option","correct":"import { Option } from 'rc-select';"},{"note":"rc-select is unstyled by default. This import provides the basic functional styles required for the component's layout and interaction. Omit if providing entirely custom styles.","symbol":"CSS Styles","correct":"import 'rc-select/assets/index.css';"},{"note":"For TypeScript users, import types separately for prop definitions and enhanced development experience.","symbol":"SelectProps, OptionProps (TypeScript)","correct":"import type { SelectProps, OptionProps } from 'rc-select';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport Select, { Option } from 'rc-select';\nimport 'rc-select/assets/index.css';\n\nconst MySelectComponent = () => {\n const [value, setValue] = useState('lucy');\n\n const handleChange = (newValue) => {\n console.log(`Selected: ${newValue}`);\n setValue(newValue);\n };\n\n return (\n
\n

Basic Select

\n \n \n \n \n \n \n

Multiple Select

\n console.log('Multiple selected:', values)}\n >\n \n \n \n \n
\n );\n};\n\nexport default MySelectComponent;","lang":"typescript","description":"Demonstrates basic usage of the Select component with single and multiple selection, including controlled and uncontrolled examples, and necessary CSS import."},"warnings":[{"fix":"Ensure `import 'rc-select/assets/index.css';` is present in your entry file or component, or apply your own custom styles targeting `rc-select`'s DOM structure.","message":"rc-select is a headless component and does not include any default visual styles beyond basic layout. Developers must import `rc-select/assets/index.css` or provide their own comprehensive CSS for the component to be visually usable. Forgetting this can lead to an invisible or poorly rendered component.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use either `value` and `onChange` together for controlled components, or `defaultValue` for uncontrolled components. Do not switch between them without managing component state properly.","message":"Older versions (e.g., v4.8.0) introduced a change to make the `value` prop a controlled property. Mixing controlled (`value` prop present) and uncontrolled (`defaultValue` prop present) usage, or removing the `value` prop without providing `defaultValue`, can lead to unexpected component behavior or state issues.","severity":"breaking","affected_versions":"<5.0.0 (historical change, still a common footgun)"},{"fix":"Ensure that all children passed directly to `Select` are `Option` components. For dynamic options, map an array of data to `Option` components.","message":"The `Option` component should only be rendered as a direct child of `Select`. Passing non-`Option` children or attempting to use `Option` outside of a `Select` component will likely result in rendering issues or runtime errors, as `Select` expects specific child types for its functionality.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Initialize `value` to an empty array (`[]`) for multiple selects or `null`/`undefined` for single selects if no initial selection is desired, and ensure `onChange` updates the state with the correct type.","cause":"Often occurs when the `value` prop for Select (especially in `multiple` mode) is `null` or `undefined` instead of an empty array or a valid array of selected values.","error":"Uncaught TypeError: Cannot read properties of undefined (reading 'map') or (reading 'length')"},{"fix":"Review the props and children passed to `Select`. Ensure any `render` props (e.g., `dropdownRender`) return a single React element. Also, check that `Option` components are correctly structured.","cause":"Can occur if `rc-select` expects a single element but receives multiple or `null`, often related to internal wrapper components or misconfigured children.","error":"Error: React.Children.only expected to receive a single React element child."},{"fix":"Verify the `rc-select` package is installed (`npm install rc-select` or `yarn add rc-select`). Confirm the import path `import 'rc-select/assets/index.css';` is correct and not mistyped.","cause":"The CSS file for `rc-select` is not found by the bundler. This typically happens if the import path is incorrect, or the package is not installed correctly.","error":"Module not found: Can't resolve 'rc-select/assets/index.css'"}],"ecosystem":"npm"}