React Select

https://react-select.com/
Admin
React Select is a flexible and beautiful Select Input control for ReactJS with multiselect,...
Tokens:15,616
Snippets:260
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install react-select with Yarn or npm

Source: https://react-select.com/home

Install react-select with either Yarn or npm. The two commands are alternative package manager choices for the same installation step.

```bash
yarn add react-select

```

```bash
npm i --save react-select

```

--------------------------------

### Import and render a basic Select with options

Source: https://react-select.com/home

Import the default Select export and render it with an options array. This is the minimal setup for a basic single select.

```jsx
import React from 'react'
import Select from 'react-select'

const options = [
  { value: 'chocolate', label: 'Chocolate' },
  { value: 'strawberry', label: 'Strawberry' },
  { value: 'vanilla', label: 'Vanilla' }
]

const MyComponent = () => (
  <Select options={options} />
)

```

--------------------------------

### Server Rendering React-Select with renderToString

Source: https://react-select.com/advanced

Use React's renderToString to server-render React-Select; Emotion provides zero-config server rendering, so no extra setup is needed. Works with frameworks like Next.js or Gatsby.

```jsx
import { renderToString } from 'react-dom/server'
import App from './App'

const html = renderToString(<App />)

```

--------------------------------

### Custom component styling with cx and getStyles

Source: https://react-select.com/styles

Example of configuring a custom component with the correct styling functionality. It imports css from emotion, uses getStyles to compute base styles, and cx to compose BEM-style modifiers based on state (isDisabled, isFocused, isSelected). The component receives cx, children, getStyles, innerRef, and other props.

```jsx
import { css } from 'emotion';

const CustomOption = ({ cx, children, getStyles, innerRef, ...props }) => (
  <div
    ref={innerRef}
    className={cx(
      css(getStyles('option', props)),
      {
        'option': true,
        'option--is-disabled': isDisabled,
        'option--is-focused': isFocused,
        'option--is-selected': isSelected,
      }
    )}
  >
    {children}
  </div>
)

```

--------------------------------

### Using the styles prop to customize the control component

Source: https://react-select.com/styles

The styles prop takes an object with keys for each inner component. Each key is a callback that receives baseStyles and state, and returns the new styles. In this example, the control's border color changes based on the isFocused state.

```jsx
<Select
  styles={{
    control: (baseStyles, state) => ({
      ...baseStyles,
      borderColor: state.isFocused ? 'grey' : 'red',
    }),
  }}
/>

```

--------------------------------

### Using the classNames prop to apply CSS classes to the control component

Source: https://react-select.com/styles

The classNames prop, available since version 5.7.0, takes an object with keys for each inner component. Each key is a callback that receives the state and returns a class name string. In this example, the control gets a different border class based on the isFocused state.

```jsx
<Select
  classNames={{
    control: (state) =>
      state.isFocused ? 'border-red-600' : 'border-grey-300',
  }}
/>

```

--------------------------------

### Wrapping Select with Custom Component

Source: https://react-select.com/typescript

Example of a custom wrapper component that re-declares the three generics (Option, IsMulti, Group) and forwards them to the underlying Select while customizing the theme.

```typescript
function CustomSelect<
  Option,
  IsMulti extends boolean = false,
  Group extends GroupBase<Option> = GroupBase<Option>
>(props: Props<Option, IsMulti, Group>) {
  return (
    <Select {...props} theme={(theme) => ({ ...theme, borderRadius: 0 })} />
  );
}
```

--------------------------------

### React Select with classNamePrefix

Source: https://react-select.com/styles

JSX example showing how to use the `classNamePrefix` prop to prefix all inner element class names. The `className` prop sets the container class, and `classNamePrefix` adds a prefix to all inner elements.

```jsx
<Select
  {...props}
  className="react-select-container"
  classNamePrefix="react-select"
/>

```

--------------------------------

### Custom Option Component with isDisabled check

Source: https://react-select.com/components

A complete example of replacing the Option component. It renders a div with innerProps unless isDisabled is true, then returns null. The component is passed to Select via components={{ Option: CustomOption }}.

```jsx
import React from 'react';
import Select from 'react-select';

const CustomOption = ({ innerProps, isDisabled }) =>
  !isDisabled ? (
    <div {...innerProps}>{/* your component internals */}</div>
  ) : null;

class Component extends React.Component {
  render() {
    return <Select components={{ Option: CustomOption }} />;
  }
}
```

--------------------------------

### New Async import from 'react-select/async'

Source: https://react-select.com/upgrade

New import for Async from the dedicated entry point `react-select/async` in v3.0.0.

```javascript
import AsyncSelect from 'react-select/async'

```

--------------------------------

### Old Async import from 'react-select'

Source: https://react-select.com/upgrade

Old import for Async from the main entry point, removed in v3.0.0.

```javascript
import { Async } from 'react-select'

```

--------------------------------

### Old Async import from 'react-select/lib/Async'

Source: https://react-select.com/upgrade

Alternative old import for Async from the lib path, also removed in v3.0.0.

```javascript
import Async from 'react-select/lib/Async'

```

--------------------------------

### v4: Construct Select with manageState HOC

Source: https://react-select.com/upgrade

Shows the previous v4 construction of the state-managed Select component using the manageState HOC.

```javascript
const Select = manageState(SelectBase);

```

--------------------------------

### Import AsyncSelect from react-select/async

Source: https://react-select.com/home

Import the AsyncSelect component from react-select/async to load options from a remote source as the user types.

```jsx
import AsyncSelect from 'react-select/async';

```

--------------------------------

### Default createFilter configuration

Source: https://react-select.com/advanced

Shows the default configuration object used by the createFilter function. It includes options for case sensitivity, accent handling, match position, stringification, and trimming.

```javascript
// default filter configuration
ignoreCase: true,
ignoreAccents: true,
matchFrom: 'any',
stringify: option => `${option.label} ${option.value}`,
trim: true,

```

--------------------------------

### v5: Construct Select with useStateManager hook

Source: https://react-select.com/upgrade

Shows the v5 construction of the state-managed Select component using the useStateManager hook.

```jsx
const Select = (props) => {
  const baseSelectProps = useStateManager(props);
  return <SelectBase {...baseSelectProps} />;
};

```

--------------------------------

### Import Async and useAsync from react-select/async

Source: https://react-select.com/async

Import the Async component and useAsync hook from react-select/async to enable remote option loading in a React Select control.

```javascript
import Async, { useAsync } from 'react-select/async';
```

--------------------------------

### Import Creatable component

Source: https://react-select.com/creatable

Import the Creatable component and the useCreatable hook from the react-select/creatable package.

```javascript
import Creatable, { useCreatable } from 'react-select/creatable';
```

--------------------------------

### Import Creatable from react-select/creatable

Source: https://react-select.com/home

Import the Creatable component from react-select/creatable to enable users to create new options along with choosing existing ones.

```jsx
import Creatable from 'react-select/creatable';

```

--------------------------------

### DOM structure with classNamePrefix

Source: https://react-select.com/styles

HTML structure that results from using `classNamePrefix="react-select"`. Shows how the prefix is applied to inner elements like `react-select__control`, `react-select__value-container`, and `react-select__option`.

```html
<div class="react-select-container">
  <div class="react-select__control">
    <div class="react-select__value-container">...</div>
    <div class="react-select__indicators">...</div>
  </div>
  <div class="react-select__menu">
    <div class="react-select__menu-list">
      <div class="react-select__option">...</div>
    </div>
  </div>
</div>

```

--------------------------------

### Custom Option with Emotion 9 (before upgrade)

Source: https://react-select.com/upgrade

Custom Option component using Emotion 9's `css` import and `classNames` prop. This is the pre-3.0.0 pattern that breaks with the Emotion 10 upgrade.

```javascript
import { css } from 'emotion'

const customOption = ({ cx, className, getStyles, _ }) =>
  <div
     classNames={cx(
       css(getStyles('option', props)),
       {
         'option': true,
         'option--is-disabled': isDisabled,
         'option--is-focused': isFocused,
         'option--is-selected': isSelected,
        },
        className
     )}
     {...}
  >

```

--------------------------------

### Import makeAnimated from react-select/animated

Source: https://react-select.com/home

Import the makeAnimated function from react-select/animated. It creates animated wrappers around components passed as arguments; if no arguments are passed, built-in components are wrapped instead.

```jsx
import makeAnimated from 'react-select/animated';

```

--------------------------------

### getStyles method signature

Source: https://react-select.com/styles

Signature of the getStyles method passed to each component. The key is a lowercased string corresponding to the component (e.g., 'option' for Option, 'menuplacer' for MenuPlacer). The props argument contains relevant state values like isFocused or isSelected, and additional props can be added for computation.

```typescript
(key: string, props: Object) => stylesObject;

```

--------------------------------

### Custom Option with Emotion 10 (after upgrade)

Source: https://react-select.com/upgrade

Custom Option component using Emotion 10's `@emotion/core` and the `css` prop. Required for react-select 3.0.0 and later.

```javascript
/** @jsx jsx */
import { jsx } from '@emotion/core';

const customOption = ({ cx, className, getStyles, _ }) =>
  <div
    css={getStyles('option', props)}
    classNames={cx(
     {
       'option': true,
       'option--is-disabled': isDisabled,
       'option--is-focused': isFocused,
       'option--is-selected': isSelected,
      },
      className
    )}
    {...}
  >

```

--------------------------------

### Define custom components outside Select scope to avoid remounting

Source: https://react-select.com/components

Shows the correct way to define custom components for react-select. Defining a component inline in the `components` prop causes remounting issues and loss of state; instead, declare the custom component outside the Select scope and pass it via the `components` prop.

```jsx
// Bad: Inline declaration will cause remounting issues
const BadSelect = props => (
  <Select {...props} components={{
    Control: ({ children, ...rest }) => (
      <components.Control {...rest}>
        👎 {children}
      </components.Control>
    )}}
  />
)

// Good: Custom component declared outside of the Select scope
const Control = ({ children, ...props }) => (
  <components.Control {...props}>
    👍 {children}
  </components.Control>
);

const GoodSelect = props => <Select {...props} components={{ Control }} />

```

--------------------------------

### Single Select onChange typing

Source: https://react-select.com/typescript

Type the onChange callback for a single-select. The first argument is Option | null.

```typescript
const onChange = (option: Option | null, actionMeta: ActionMeta<Option>) => {
   ...
}
```

--------------------------------

### Update type imports from react-select/src to dist/declarations/src

Source: https://react-select.com/upgrade

When upgrading from v4 to v5, replace imports from 'react-select/src/...' with imports from 'react-select/dist/declarations/src/...' for types that were previously provided by @types/react-select. The first snippet shows the old import path, the second shows the new one.

```typescript
import { ... } from 'react-select/src/...';

```

```typescript
import { ... } from 'react-select/dist/declarations/src/...';

```

--------------------------------

### GroupBase Type Definition

Source: https://react-select.com/typescript

The GroupBase<Option> interface defines the structure for groups passed into the options prop. It includes a read-only options array and an optional label. Useful when typing the formatGroupLabel prop.

```typescript
interface GroupBase<Option> {
  readonly options: readonly Option[];
  readonly label?: string;
}
```

--------------------------------

### Before: handle null onChange with nullish coalescing

Source: https://react-select.com/upgrade

Before the upgrade, when isMulti was true, onChange could pass null, so nullish coalescing was used to default to an empty array.

```jsx
<Select isMulti onChange={(newValues) => setValues(newValues ?? [])} />
```

--------------------------------

### Custom filterOption including Create option

Source: https://react-select.com/advanced

Custom filterOption function that always includes the 'Create' option for creatable selects. It returns true if the candidate is new or if its label includes the input.

```javascript
const filterOption = (candidate, input) => {
  return candidate.data.__isNew__ || candidate.label.includes(input);
};

```

--------------------------------

### cx utility function signature

Source: https://react-select.com/styles

Signature of the cx utility function passed to custom components. It composes emotion style declarations, className/classNamePrefixes, and BEM-style modifiers into a selector string. Parameters: prefix (optional classNamePrefix), cssKey (uid from emotion's css method), state (object with state-based modifiers), and className (custom className prop).

```typescript
(prefix ?: string,
  cssKey?: string,
  state?: {},
  className?: string) => string

```

--------------------------------

### Module Augmentation for Custom Props

Source: https://react-select.com/typescript

Use module augmentation to add custom props to the Select prop types. This requires importing 'react-select/base' and declaring the Props interface with the custom prop 'myCustomProp', making it available when using Select or accessing selectProps.

```typescript
import type {} from 'react-select/base';
// This import is necessary for module augmentation.
// It allows us to extend the 'Props' interface in the 'react-select/base' module
// and add our custom property 'myCustomProp' to it.

declare module 'react-select/base' {
  export interface Props<
    Option,
    IsMulti extends boolean,
    Group extends GroupBase<Option>
  > {
    myCustomProp: string;
  }
}
```

--------------------------------

### Multi Select onChange typing

Source: https://react-select.com/typescript

Type the onChange callback for a multi-select. The first argument is readonly Option[].

```typescript
const onChange = (option: readonly Option[], actionMeta: ActionMeta<Option>) => {
   ...
}
```

--------------------------------

### After: remove nullish coalescing from onChange

Source: https://react-select.com/upgrade

After the upgrade, onChange always passes an array when isMulti is true, so the nullish coalescing can be removed.

```jsx
<Select isMulti onChange={(newValues) => setValues(newValues)} />
```

--------------------------------

### Custom Option with innerRef and innerProps

Source: https://react-select.com/components

Shows a minimal custom Option component that assigns innerRef to the div's ref and spreads innerProps. innerRef is required for react-select to manage internal behavior.

```jsx
const CustomOption = ({ innerRef, innerProps }) => (
<div ref={innerRef} {...innerProps} />)
```

--------------------------------

### Interface SelectProps Generics Definition

Source: https://react-select.com/typescript

Defines the optional generics used by the Select component: Option (defaults to unknown), IsMulti (extends boolean, defaults to false), and Group (extends GroupBase<Option>). This definition helps TypeScript infer types for callbacks like onChange and option-related props.

```typescript
interface SelectProps<
  Option = unknown,
  IsMulti extends boolean = false,
  Group extends GroupBase<Option> = GroupBase<Option>
> {
 ...
}
```
Tokens:
Raw