0
# Core Components
1

2
React-Select provides four main component variants that cover different interaction patterns and use cases. Each component is fully generic and type-safe, supporting custom Option and Group types.
3

4
## Capabilities
5

6
### Select (Default Component)
7

8
The main select component with built-in state management for standard dropdown interactions.
9

10
```typescript { .api }
11
/**
12
 * Main select component with built-in state management
13
 * @param props - Complete Props interface with 69+ configuration options
14
 * @returns JSX.Element representing the select component
15
 */
16
function Select<
17
  Option = unknown,
18
  IsMulti extends boolean = false,
19
  Group extends GroupBase<Option> = GroupBase<Option>
20
>(props: Props<Option, IsMulti, Group>): JSX.Element;
21

22
interface Props<Option, IsMulti extends boolean, Group extends GroupBase<Option>> {
23
  // Core Data Props
24
  options: OptionsOrGroups<Option, Group>;
25
  value?: PropsValue<Option>;
26
  defaultValue?: PropsValue<Option>;
27
  isMulti?: IsMulti;
28
  
29
  // Event Handlers
30
  onChange?: (newValue: OnChangeValue<Option, IsMulti>, actionMeta: ActionMeta<Option>) => void;
31
  onInputChange?: (newValue: string, actionMeta: InputActionMeta) => void;
32
  onMenuOpen?: () => void;
33
  onMenuClose?: () => void;
34
  onFocus?: FocusEventHandler<HTMLInputElement>;
35
  onBlur?: FocusEventHandler<HTMLInputElement>;
36
  
37
  // Behavior Configuration
38
  isSearchable?: boolean;
39
  isClearable?: boolean;
40
  isDisabled?: boolean;
41
  isLoading?: boolean;
42
  autoFocus?: boolean;
43
  openMenuOnClick?: boolean;
44
  openMenuOnFocus?: boolean;
45
  closeMenuOnSelect?: boolean;
46
  closeMenuOnScroll?: boolean | ((event: Event) => boolean);
47
  
48
  // Display Options
49
  placeholder?: ReactNode;
50
  noOptionsMessage?: (obj: { inputValue: string }) => ReactNode;
51
  loadingMessage?: (obj: { inputValue: string }) => ReactNode;
52
  
53
  // Data Processing
54
  getOptionLabel?: (option: Option) => string;
55
  getOptionValue?: (option: Option) => string;
56
  getOptionValue?: (option: Option) => string;
57
  isOptionDisabled?: (option: Option, selectValue: Options<Option>) => boolean;
58
  isOptionSelected?: (option: Option, selectValue: Options<Option>) => boolean;
59
  filterOption?: ((option: FilterOptionOption<Option>, inputValue: string) => boolean) | null;
60
  
61
  // Menu Configuration
62
  menuIsOpen?: boolean;
63
  menuPlacement?: MenuPlacement;
64
  menuPosition?: MenuPosition;
65
  menuPortalTarget?: HTMLElement | null;
66
  maxMenuHeight?: number;
67
  minMenuHeight?: number;
68
  
69
  // Styling
70
  className?: string;
71
  classNamePrefix?: string;
72
  classNames?: ClassNamesConfig<Option, IsMulti, Group>;
73
  styles?: StylesConfig<Option, IsMulti, Group>;
74
  theme?: ThemeConfig;
75
  unstyled?: boolean;
76
  
77
  // Component Customization
78
  components?: SelectComponentsConfig<Option, IsMulti, Group>;
79
  
80
  // Accessibility
81
  'aria-label'?: string;
82
  'aria-labelledby'?: string;
83
  'aria-describedby'?: string;
84
  ariaLiveMessages?: AriaLiveMessages<Option, IsMulti, Group>;
85
  
86
  // Form Integration
87
  name?: string;
88
  id?: string;
89
  inputId?: string;
90
  instanceId?: number | string;
91
  required?: boolean;
92
  form?: string;
93
}
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import Select from "react-select";
100

101
// Basic single-select
102
const BasicSelect = () => (
103
  <Select
104
    options={[
105
      { value: "red", label: "Red" },
106
      { value: "green", label: "Green" },
107
      { value: "blue", label: "Blue" },
108
    ]}
109
    placeholder="Choose a color..."
110
  />
111
);
112

113
// Multi-select with controlled state
114
const MultiSelect = () => {
115
  const [selectedOptions, setSelectedOptions] = useState([]);
116
  
117
  return (
118
    <Select
119
      isMulti
120
      value={selectedOptions}
121
      onChange={setSelectedOptions}
122
      options={colorOptions}
123
      closeMenuOnSelect={false}
124
    />
125
  );
126
};
127

128
// Disabled and clearable select
129
const ConfiguredSelect = () => (
130
  <Select
131
    options={options}
132
    isDisabled={false}
133
    isClearable
134
    isSearchable
135
    placeholder="Search and select..."
136
  />
137
);
138
```
139

140
### AsyncSelect
141

142
Select component with async option loading capabilities for dynamic data fetching.
143

144
```typescript { .api }
145
/**
146
 * Select component with async option loading
147
 * @param props - Props interface extended with async-specific properties
148
 * @returns JSX.Element with async loading capabilities
149
 */
150
function AsyncSelect<
151
  Option = unknown,
152
  IsMulti extends boolean = false,
153
  Group extends GroupBase<Option> = GroupBase<Option>
154
>(props: Props<Option, IsMulti, Group> & AsyncProps<Option>): JSX.Element;
155

156
interface AsyncProps<Option> {
157
  /** Default options to show before any input, or true to load options immediately */
158
  defaultOptions?: OptionsOrGroups<Option, Group> | boolean;
159
  /** Enable caching of loaded options */
160
  cacheOptions?: any;
161
  /** Function to load options asynchronously based on input value */
162
  loadOptions?: (
163
    inputValue: string,
164
    callback: (options: OptionsOrGroups<Option, Group>) => void
165
  ) => Promise<OptionsOrGroups<Option, Group>> | void;
166
}
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import AsyncSelect from "react-select/async";
173

174
// Basic async select
175
const AsyncExample = () => {
176
  const loadOptions = (inputValue: string) =>
177
    new Promise<Option[]>((resolve) => {
178
      setTimeout(() => {
179
        resolve(
180
          colorOptions.filter((option) =>
181
            option.label.toLowerCase().includes(inputValue.toLowerCase())
182
          )
183
        );
184
      }, 1000);
185
    });
186

187
  return (
188
    <AsyncSelect
189
      cacheOptions
190
      defaultOptions
191
      loadOptions={loadOptions}
192
      placeholder="Type to search..."
193
    />
194
  );
195
};
196

197
// Async with callback pattern
198
const CallbackAsync = () => {
199
  const loadOptions = (inputValue: string, callback: Function) => {
200
    setTimeout(() => {
201
      callback(
202
        inputValue
203
          ? colorOptions.filter((option) =>
204
              option.label.toLowerCase().includes(inputValue.toLowerCase())
205
            )
206
          : colorOptions
207
      );
208
    }, 1000);
209
  };
210

211
  return <AsyncSelect loadOptions={loadOptions} />;
212
};
213
```
214

215
### CreatableSelect
216

217
Select component with the ability to create new options that don't exist in the options list.
218

219
```typescript { .api }
220
/**
221
 * Select component with option creation capability
222
 * @param props - Props interface extended with creatable-specific properties
223
 * @returns JSX.Element with option creation features
224
 */
225
function CreatableSelect<
226
  Option = unknown,
227
  IsMulti extends boolean = false,
228
  Group extends GroupBase<Option> = GroupBase<Option>
229
>(props: Props<Option, IsMulti, Group> & CreatableProps<Option>): JSX.Element;
230

231
interface CreatableProps<Option> {
232
  /** Allow creating options while async loading is in progress */
233
  allowCreateWhileLoading?: boolean;
234
  /** Position of the create option in the menu */
235
  createOptionPosition?: 'first' | 'last';
236
  /** Custom formatter for the create option label */
237
  formatCreateLabel?: (inputValue: string) => ReactNode;
238
  /** Validation function to determine if new option creation is allowed */
239
  isValidNewOption?: (
240
    inputValue: string,
241
    value: Options<Option>,
242
    options: OptionsOrGroups<Option, Group>,
243
    accessors: { getOptionValue: GetOptionValue<Option>; getOptionLabel: GetOptionLabel<Option> }
244
  ) => boolean;
245
  /** Function to generate data for new options */
246
  getNewOptionData?: (inputValue: string, optionLabel: ReactNode) => Option;
247
  /** Handler called when a new option is created */
248
  onCreateOption?: (inputValue: string) => void;
249
}
250
```
251

252
**Usage Examples:**
253

254
```typescript
255
import CreatableSelect from "react-select/creatable";
256

257
// Basic creatable select
258
const CreatableExample = () => {
259
  const [options, setOptions] = useState(initialOptions);
260
  
261
  const handleCreate = (inputValue: string) => {
262
    const newOption = { value: inputValue.toLowerCase(), label: inputValue };
263
    setOptions((prev) => [...prev, newOption]);
264
  };
265

266
  return (
267
    <CreatableSelect
268
      options={options}
269
      onCreateOption={handleCreate}
270
      formatCreateLabel={(inputValue) => `Create "${inputValue}"`}
271
    />
272
  );
273
};
274

275
// Advanced creatable with validation
276
const ValidatedCreatable = () => {
277
  const isValidNewOption = (inputValue: string) => {
278
    return inputValue.length >= 3 && !options.some(
279
      option => option.label.toLowerCase() === inputValue.toLowerCase()
280
    );
281
  };
282

283
  return (
284
    <CreatableSelect
285
      options={options}
286
      isValidNewOption={isValidNewOption}
287
      formatCreateLabel={(inputValue) => 
288
        inputValue.length < 3 
289
          ? `"${inputValue}" is too short` 
290
          : `Add "${inputValue}"`
291
      }
292
    />
293
  );
294
};
295
```
296

297
### AsyncCreatableSelect
298

299
Combines async data loading with option creation capabilities.
300

301
```typescript { .api }
302
/**
303
 * Select component combining async loading and option creation
304
 * @param props - Props interface with both async and creatable properties
305
 * @returns JSX.Element with both async and creation capabilities
306
 */
307
function AsyncCreatableSelect<
308
  Option = unknown,
309
  IsMulti extends boolean = false,
310
  Group extends GroupBase<Option> = GroupBase<Option>
311
>(
312
  props: Props<Option, IsMulti, Group> & AsyncProps<Option> & CreatableProps<Option>
313
): JSX.Element;
314
```
315

316
**Usage Examples:**
317

318
```typescript
319
import AsyncCreatableSelect from "react-select/async-creatable";
320

321
// Async creatable select
322
const AsyncCreatableExample = () => {
323
  const loadOptions = (inputValue: string) =>
324
    fetchOptionsFromAPI(inputValue);
325

326
  const handleCreate = (inputValue: string) => {
327
    return createNewOptionAPI(inputValue);
328
  };
329

330
  return (
331
    <AsyncCreatableSelect
332
      cacheOptions
333
      defaultOptions
334
      loadOptions={loadOptions}
335
      onCreateOption={handleCreate}
336
      allowCreateWhileLoading
337
    />
338
  );
339
};
340
```
341

342
### Base Select Component
343

344
Unstyled base select component without state management for maximum customization.
345

346
```typescript { .api }
347
/**
348
 * Base select component without state management
349
 * @param props - Raw Props interface without state management
350
 * @returns JSX.Element with minimal built-in behavior
351
 */
352
function BaseSelect<
353
  Option = unknown,
354
  IsMulti extends boolean = false,
355
  Group extends GroupBase<Option> = GroupBase<Option>
356
>(props: PublicBaseSelectProps<Option, IsMulti, Group>): JSX.Element;
357
```
358

359
## State Management Hook
360

361
### useStateManager
362

363
Hook for managing select state externally while using the base component.
364

365
```typescript { .api }
366
/**
367
 * State management hook for select components
368
 * @param props - State manager props configuration
369
 * @returns Props object for base select component
370
 */
371
function useStateManager<
372
  Option = unknown,
373
  IsMulti extends boolean = false,
374
  Group extends GroupBase<Option> = GroupBase<Option>
375
>(
376
  props: StateManagerProps<Option, IsMulti, Group>
377
): PublicBaseSelectProps<Option, IsMulti, Group>;
378

379
interface StateManagerProps<Option, IsMulti extends boolean, Group extends GroupBase<Option>>
380
  extends Omit<Props<Option, IsMulti, Group>, keyof ControlledProps> {
381
  defaultInputValue?: string;
382
  defaultMenuIsOpen?: boolean;
383
  defaultValue?: PropsValue<Option>;
384
}
385
```
386

387
**Usage Example:**
388

389
```typescript
390
import BaseSelect from "react-select/base";
391
import { useStateManager } from "react-select";
392

393
const CustomSelect = (props) => {
394
  const selectProps = useStateManager(props);
395
  
396
  return <BaseSelect {...selectProps} />;
397
};
398
```
399

400
## Component Instance Reference
401

402
### SelectInstance
403

404
Type representing a Select component instance with available methods.
405

406
```typescript { .api }
407
interface SelectInstance<
408
  Option = unknown,
409
  IsMulti extends boolean = false,
410
  Group extends GroupBase<Option> = GroupBase<Option>
411
> {
412
  /** Focus the select input */
413
  focus(): void;
414
  /** Blur the select input */
415
  blur(): void;
416
  /** Get current select value */
417
  getValue(): OnChangeValue<Option, IsMulti>;
418
  /** Check if menu is open */
419
  getMenuIsOpen(): boolean;
420
  /** Get current input value */
421
  getInputValue(): string;
422
}
423
```
424

425
**Usage Example:**
426

427
```typescript
428
import { useRef } from "react";
429
import Select, { SelectInstance } from "react-select";
430

431
const ComponentWithRef = () => {
432
  const selectRef = useRef<SelectInstance<Option>>(null);
433
  
434
  const focusSelect = () => {
435
    selectRef.current?.focus();
436
  };
437
  
438
  return (
439
    <>
440
      <Select ref={selectRef} options={options} />
441
      <button onClick={focusSelect}>Focus Select</button>
442
    </>
443
  );
444
};
445
```