0
# React-Select
1
2
React-Select is a comprehensive and flexible select component library for React applications that provides a powerful, customizable dropdown interface with support for single and multi-select functionality, async data loading, search filtering, and custom option rendering. Built with TypeScript and Emotion for styling, it offers extensive customization through component injection APIs, controllable state props, and a modular architecture.
3
4
## Package Information
5
6
- **Package Name**: react-select
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-select`
10
11
## Core Imports
12
13
```typescript
14
import Select from "react-select";
15
import AsyncSelect from "react-select/async";
16
import CreatableSelect from "react-select/creatable";
17
import AsyncCreatableSelect from "react-select/async-creatable";
18
import makeAnimated from "react-select/animated";
19
import { components, createFilter, mergeStyles, defaultTheme } from "react-select";
20
```
21
22
For CommonJS:
23
24
```javascript
25
const Select = require("react-select").default;
26
const AsyncSelect = require("react-select/async").default;
27
const CreatableSelect = require("react-select/creatable").default;
28
const AsyncCreatableSelect = require("react-select/async-creatable").default;
29
const makeAnimated = require("react-select/animated").default;
30
const { components, createFilter, mergeStyles, defaultTheme } = require("react-select");
31
```
32
33
## Basic Usage
34
35
```typescript
36
import Select from "react-select";
37
38
interface Option {
39
value: string;
40
label: string;
41
}
42
43
const options: Option[] = [
44
{ value: "chocolate", label: "Chocolate" },
45
{ value: "strawberry", label: "Strawberry" },
46
{ value: "vanilla", label: "Vanilla" },
47
];
48
49
function MyComponent() {
50
const [selectedOption, setSelectedOption] = useState<Option | null>(null);
51
52
return (
53
<Select
54
value={selectedOption}
55
onChange={setSelectedOption}
56
options={options}
57
placeholder="Select a flavor..."
58
isSearchable
59
/>
60
);
61
}
62
```
63
64
## Architecture
65
66
React-Select is built around several key architectural components:
67
68
- **Core Select Components**: Main select variants (Select, AsyncSelect, CreatableSelect, AsyncCreatableSelect) providing different interaction patterns
69
- **Component System**: 25+ customizable sub-components that can be replaced or modified to change behavior and appearance
70
- **State Management**: Built-in state management with hooks (`useStateManager`) or controllable props for external state
71
- **Type System**: Full TypeScript support with generic types for Option and Group data structures
72
- **Styling System**: Emotion-based styling with theme support, custom styles, and CSS class customization
73
- **Accessibility**: ARIA compliance with customizable live region messages and keyboard navigation
74
75
## Capabilities
76
77
### Core Select Components
78
79
Main select component variants providing different interaction patterns and capabilities.
80
81
```typescript { .api }
82
function Select<Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
83
props: Props<Option, IsMulti, Group>
84
): JSX.Element;
85
86
function AsyncSelect<Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
87
props: Props<Option, IsMulti, Group> & AsyncProps<Option>
88
): JSX.Element;
89
90
function CreatableSelect<Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
91
props: Props<Option, IsMulti, Group> & CreatableProps<Option>
92
): JSX.Element;
93
94
function AsyncCreatableSelect<Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
95
props: Props<Option, IsMulti, Group> & AsyncProps<Option> & CreatableProps<Option>
96
): JSX.Element;
97
```
98
99
[Core Components](./core-components.md)
100
101
### Async Data Loading
102
103
Async data loading capabilities for dynamic option fetching with caching and loading state management.
104
105
```typescript { .api }
106
interface AsyncProps<Option> {
107
defaultOptions?: OptionsOrGroups<Option, Group> | boolean;
108
cacheOptions?: any;
109
loadOptions?: (inputValue: string, callback: Function) => Promise<OptionsOrGroups<Option, Group>>;
110
}
111
```
112
113
[Async Data Loading](./async-data.md)
114
115
### Component Customization
116
117
Comprehensive component customization system allowing replacement or modification of any UI element.
118
119
```typescript { .api }
120
interface SelectComponentsConfig<Option, IsMulti extends boolean, Group extends GroupBase<Option>> {
121
ClearIndicator?: ComponentType<ClearIndicatorProps<Option, IsMulti, Group>>;
122
Control?: ComponentType<ControlProps<Option, IsMulti, Group>>;
123
DropdownIndicator?: ComponentType<DropdownIndicatorProps<Option, IsMulti, Group>>;
124
DownChevron?: ComponentType<any>;
125
CrossIcon?: ComponentType<any>;
126
Group?: ComponentType<GroupProps<Option, IsMulti, Group>>;
127
GroupHeading?: ComponentType<GroupHeadingProps<Option, IsMulti, Group>>;
128
IndicatorsContainer?: ComponentType<IndicatorsContainerProps<Option, IsMulti, Group>>;
129
IndicatorSeparator?: ComponentType<IndicatorSeparatorProps<Option, IsMulti, Group>>;
130
Input?: ComponentType<InputProps<Option, IsMulti, Group>>;
131
LoadingIndicator?: ComponentType<LoadingIndicatorProps<Option, IsMulti, Group>>;
132
Menu?: ComponentType<MenuProps<Option, IsMulti, Group>>;
133
MenuList?: ComponentType<MenuListProps<Option, IsMulti, Group>>;
134
MenuPortal?: ComponentType<MenuPortalProps<Option, IsMulti, Group>>;
135
LoadingMessage?: ComponentType<NoticeProps<Option, IsMulti, Group>>;
136
NoOptionsMessage?: ComponentType<NoticeProps<Option, IsMulti, Group>>;
137
MultiValue?: ComponentType<MultiValueProps<Option, IsMulti, Group>>;
138
MultiValueContainer?: ComponentType<MultiValueGenericProps<Option, IsMulti, Group>>;
139
MultiValueLabel?: ComponentType<MultiValueGenericProps<Option, IsMulti, Group>>;
140
MultiValueRemove?: ComponentType<MultiValueRemoveProps<Option, IsMulti, Group>>;
141
Option?: ComponentType<OptionProps<Option, IsMulti, Group>>;
142
Placeholder?: ComponentType<PlaceholderProps<Option, IsMulti, Group>>;
143
SelectContainer?: ComponentType<ContainerProps<Option, IsMulti, Group>>;
144
SingleValue?: ComponentType<SingleValueProps<Option, IsMulti, Group>>;
145
ValueContainer?: ComponentType<ValueContainerProps<Option, IsMulti, Group>>;
146
}
147
```
148
149
[Customization](./customization.md)
150
151
### Core Types and Interfaces
152
153
Complete type system supporting generic Option and Group types with full TypeScript integration.
154
155
```typescript { .api }
156
interface GroupBase<Option> {
157
readonly options: readonly Option[];
158
readonly label?: string;
159
}
160
161
type Options<Option> = readonly Option[];
162
type SingleValue<Option> = Option | null;
163
type MultiValue<Option> = readonly Option[];
164
type OnChangeValue<Option, IsMulti extends boolean> = IsMulti extends true ? MultiValue<Option> : SingleValue<Option>;
165
166
interface ActionMeta<Option> {
167
action: 'select-option' | 'deselect-option' | 'remove-value' | 'pop-value' | 'set-value' | 'clear' | 'create-option';
168
name?: string;
169
option?: Option;
170
removedValue?: Option;
171
removedValues?: Option[];
172
}
173
```
174
175
[Types and Interfaces](./types-interfaces.md)
176
177
### Animated Components
178
179
Animated components system providing smooth transitions for multi-select values and other UI elements.
180
181
```typescript { .api }
182
function makeAnimated(
183
externalComponents?: Partial<SelectComponentsGeneric>
184
): Partial<SelectComponentsGeneric>;
185
186
interface AnimatedComponents {
187
Input: ComponentType<InputProps<any, any, any>>;
188
MultiValue: ComponentType<MultiValueProps<any, any, any>>;
189
Placeholder: ComponentType<PlaceholderProps<any, any, any>>;
190
SingleValue: ComponentType<SingleValueProps<any, any, any>>;
191
ValueContainer: ComponentType<ValueContainerProps<any, any, any>>;
192
}
193
```
194
195
[Animated Components](./customization.md#animated-components)
196
197
### Hooks and State Management
198
199
Core hooks for state management and advanced component integration.
200
201
```typescript { .api }
202
function useStateManager<Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
203
props: StateManagerProps<Option, IsMulti, Group>
204
): StateManagerReturn<Option, IsMulti, Group>;
205
206
function useAsync<Option>(
207
props: AsyncProps<Option>
208
): AsyncState<Option>;
209
210
function useCreatable<Option>(
211
props: CreatableProps<Option>
212
): CreatableState<Option>;
213
```
214
215
[Hooks and State Management](./hooks-state.md)
216
217
## Utilities
218
219
### createFilter
220
221
Factory function for creating custom filter functions with configurable matching behavior.
222
223
```typescript { .api }
224
function createFilter<Option>(config?: FilterConfig<Option>): FilterFunction<Option>;
225
226
interface FilterConfig<Option> {
227
ignoreCase?: boolean;
228
ignoreAccents?: boolean;
229
stringify?: (option: FilterOptionOption<Option>) => string;
230
trim?: boolean;
231
matchFrom?: 'any' | 'start';
232
}
233
```
234
235
### mergeStyles
236
237
Utility for merging style configurations with deep object merging.
238
239
```typescript { .api }
240
function mergeStyles<Option, IsMulti extends boolean, Group extends GroupBase<Option>>(
241
source: StylesConfig<Option, IsMulti, Group>,
242
target: StylesConfig<Option, IsMulti, Group>
243
): StylesConfig<Option, IsMulti, Group>;
244
```
245
246
### NonceProvider
247
248
CSP nonce provider component for secure style injection.
249
250
```typescript { .api }
251
function NonceProvider({ nonce, children }: { nonce: string; children: ReactNode }): JSX.Element;
252
```
253
254
### components
255
256
Object containing all individual Select sub-components for granular customization.
257
258
```typescript { .api }
259
const components: {
260
ClearIndicator: ComponentType<ClearIndicatorProps<any, any, any>>;
261
Control: ComponentType<ControlProps<any, any, any>>;
262
DropdownIndicator: ComponentType<DropdownIndicatorProps<any, any, any>>;
263
Input: ComponentType<InputProps<any, any, any>>;
264
Menu: ComponentType<MenuProps<any, any, any>>;
265
Option: ComponentType<OptionProps<any, any, any>>;
266
// ... 25+ total components
267
};
268
```
269
270
### defaultTheme
271
272
Default theme configuration object with colors and spacing definitions.
273
274
```typescript { .api }
275
const defaultTheme: {
276
colors: Colors;
277
spacing: ThemeSpacing;
278
};
279
280
interface Colors {
281
primary: string;
282
primary75: string;
283
primary50: string;
284
primary25: string;
285
danger: string;
286
dangerLight: string;
287
neutral0: string;
288
// ... additional color definitions
289
}
290
291
interface ThemeSpacing {
292
baseUnit: number;
293
controlHeight: number;
294
menuGutter: number;
295
}
296
```