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.
Select
✓ import Select from 'rc-select';
✗ const Select = require('rc-select');
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.
Option
✓ import { Option } from 'rc-select';
✗ const { Option } = require('rc-select');
Option is a named export and must be destructured. It should only be used as a direct child of the Select component.
CSS Styles
✓ import 'rc-select/assets/index.css';
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.
SelectProps, OptionProps (TypeScript)
✓ import type { SelectProps, OptionProps } from 'rc-select';
For TypeScript users, import types separately for prop definitions and enhanced development experience.
Demonstrates basic usage of the Select component with single and multiple selection, including controlled and uncontrolled examples, and necessary CSS import.
import React, { useState } from 'react';
import Select, { Option } from 'rc-select';
import 'rc-select/assets/index.css';
const MySelectComponent = () => {
const [value, setValue] = useState('lucy');
const handleChange = (newValue) => {
console.log(`Selected: ${newValue}`);
setValue(newValue);
};
return (
<div style={{ width: 200, margin: '20px auto' }}>
<h3>Basic Select</h3>
<Select
value={value}
onChange={handleChange}
placeholder="Please select..."
style={{ width: '100%' }}
>
<Option value="jack">Jack</Option>
<Option value="lucy">Lucy</Option>
<Option value="yiminghe">Yiminghe</Option>
<Option value="disabled" disabled>Disabled Option</Option>
</Select>
<h3 style={{ marginTop: '20px' }}>Multiple Select</h3>
<Select
mode="multiple"
defaultValue={['a10', 'c12']}
placeholder="Select multiple..."
style={{ width: '100%' }}
onChange={(values) => console.log('Multiple selected:', values)}
>
<Option value="a10">a10</Option>
<Option value="c12">c12</Option>
<Option value="b11">b11</Option>
</Select>
</div>
);
};
export default MySelectComponent;
Debug
Known issues
gotcharc-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.fixEnsure `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.
affects: >=1.0.0
breakingOlder 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.fixAlways use either `value` and `onChange` together for controlled components, or `defaultValue` for uncontrolled components. Do not switch between them without managing component state properly.
affects: <5.0.0 (historical change, still a common footgun)
gotchaThe `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.fixEnsure that all children passed directly to `Select` are `Option` components. For dynamic options, map an array of data to `Option` components.
affects: >=1.0.0
Errors
Common errors & fixes
Uncaught TypeError: Cannot read properties of undefined (reading 'map') or (reading 'length')
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.
fixInitialize `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.
Error: React.Children.only expected to receive a single React element child.
Can occur if `rc-select` expects a single element but receives multiple or `null`, often related to internal wrapper components or misconfigured children.
fixReview 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.
Module not found: Can't resolve 'rc-select/assets/index.css'
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.
fixVerify 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.
Audit
Dependencies
reactrequiredPeer dependency required for rendering React components.
react-domrequiredPeer dependency required for rendering React components to the DOM.