Guide · Open source

How to use react-select: install, props and examples

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-select is a React component library that provides a select control, the dropdown where users pick one or more options from a list. This guide shows how to install it, render a basic dropdown, and use the common props for searching, multiple choices and controlled state. After reading, you will be able to add a working select to a React app and know where to look for styling, async and creatable options.

React SelectJedWatson/react-select · ★ 28k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm your project uses Node.js and React, since react-select is built for React.js.
2Install the package. Run yarn add react-select in your project folder.
3Import Select. Import Select from react-select in the component where you need a dropdown.
4Define options. Create an array of objects, each with a value and a label.
5Add the component. Render Select with the options prop and, optionally, onChange and defaultValue.
6Set common props. Add props such as isMulti, isSearchable or placeholder to match your form's needs.
7Read the docs for advanced cases. Use the linked guides on styling, async loading, creatable options and TypeScript as needed.

What you need before you install react-select

react-select is a component for React.js, so your project needs React. The package is installed from npm, and the README's install example uses yarn.

Pick react-select when you need more than a plain HTML select, such as searching, multiple choices or option groups.

Node.js
React
A package manager such as yarn

Install react-select with yarn

Run this command in your project folder to add the package from npm. The README says the easiest way to use it is to install it from npm and build it into your app with Webpack.

yarn add react-select

Render a basic select component

Import Select from react-select and pass it an array of options. Each option is an object with a value and a label. The example stores the chosen option in state with useState and passes setSelectedOption to onChange.

The README example uses defaultValue, which sets the initial value while react-select manages the rest of the state.

import React, { useState } from 'react';
import Select from 'react-select';

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

export default function App() {
  const [selectedOption, setSelectedOption] = useState(null);

  return (
    <div className="App">
      <Select
        defaultValue={selectedOption}
        onChange={setSelectedOption}
        options={options}
      />
    </div>
  );
}

Use common props for behaviour and text

The README lists common props you may want to set. Useful ones for most forms include isMulti to allow several values, isSearchable to let users filter options, isDisabled to turn the control off, and placeholder to change the text shown when nothing is selected.

For a complete list, the README points to the props documentation on react-select.com.

isMulti - allow the user to select multiple values
isSearchable - allow the user to search for matching options
isDisabled - disable the control
placeholder - change the text displayed when no option is selected
name - generate an HTML input with this name, containing the current value
noOptionsMessage - returns text to display when there are no options
autoFocus - focus the control when it mounts
className and classNamePrefix - apply class names to the control and inner elements

Control the value yourself or let react-select manage it

If you provide value and onChange, you control the current value. If you leave them out, react-select manages the state for you. The README lists other controllable props, including menuIsOpen, inputValue and their change handlers.

If you do not control a prop, you can still set its starting state with defaultValue, defaultMenuIsOpen or defaultInputValue. The component also exposes focus() and blur() methods.

value / onChange - specify the current value of the control
menuIsOpen / onMenuOpen / onMenuClose - control whether the menu is open
inputValue / onInputChange - control the search input text
defaultValue, defaultMenuIsOpen, defaultInputValue - set initial state when you do not control it

Customise styling and go further

react-select has an extensible styling API built on emotion, and it supports custom components through a Component Injection API. The README links to docs on styles, custom components, animated components, async selects, creatable options and advanced use cases.

The project's v5 release is a TypeScript rewrite. The README links a TypeScript guide for using the types from v5 onward, and types for v4 and earlier are published under @types/react-select.

Styling API with emotion
Custom components through the Component Injection API
Async selects and creatable options, covered in the docs
TypeScript types from v5, with the guide on react-select.com

What people use it for

A searchable country or city picker in a signup form
A multi-select field for tags or categories with isMulti
A controlled filter dropdown whose value is stored in React state
A select with option groups, which the README lists among its long-requested features
A styled dropdown that matches a design system through the emotion-based styling API

Frequently asked questions

How do I install react-select?

Run yarn add react-select in your project folder. The README describes installing from npm and building it into your app with Webpack.

Is react-select free to use?

react-select is MIT licensed, as stated in the README's License section, which reads MIT Licensed with copyright held by Jed Watson.

What do I need to run react-select?

The project needs Node.js and React. react-select is a component for React.js and is not meant for projects that do not use React.

How do I allow multiple selections?

Pass the isMulti prop, which the README lists as allowing the user to select multiple values.

Should I use react-select or a plain HTML select?

Use react-select when you need features such as search, multiple choices or option groups. If you only need a simple native select with no extra features, a plain HTML select is the better fit.

Can I use react-select with older versions?

The README links upgrade guides for v3 through v5 and a v2 upgrade guide, and says v5 is a TypeScript rewrite. Check those guides before upgrading an older setup.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

react-select suits React developers who need a searchable, multi-select or customisable dropdown and want a component that works with little setup. It is not a fit for non-React projects, for teams that only need a native HTML select, or for anyone who must keep an old v1 or v2 setup without reading the upgrade guides.

Install options & downloads