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
```