React-Select

The Select control for React. Initially built for use in KeystoneJS.

See react-select.com for live demos and comprehensive docs.

See our upgrade guide for a breakdown on how to upgrade from v2 to v3.

React Select is funded by Thinkmill and Atlassian. It represents a whole new approach to developing powerful React.js components that just work out of the box, while being extremely customisable.

Features include:

Flexible approach to data, with customisable functions
Extensible styling API with emotion
Component Injection API for complete control over the UI behaviour
Controllable state props and modular architecture
Long-requested features like option groups, portal support, animation, and more

If you're interested in the background, watch Jed's talk on React Select at ReactNYC in March 2018.

See our upgrade guide for a breakdown on how to upgrade from v1 to v2.

The old docs and examples will continue to be available at v1.react-select.com.

Installation and usage

The easiest way to use react-select is to install it from npm and build it into your app with Webpack.

yarn add react-select

Then use it in your app:

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

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

class App extends React.Component {
  state = {
    selectedOption: null,
  };
  handleChange = selectedOption => {
    this.setState({ selectedOption });
    console.log(`Option selected:`, selectedOption);
  };
  render() {
    const { selectedOption } = this.state;

    return (
      <Select
        value={selectedOption}
        onChange={this.handleChange}
        options={options}
      />
    );
  }
}

Props

Common props you may want to specify include:

autoFocus - focus the control when it mounts
className - apply a className to the control
classNamePrefix - apply classNames to inner elements with the given prefix
isDisabled - disable the control
isMulti - allow the user to select multiple values
isSearchable - allow the user to search for matching options
name - generate an HTML input with this name, containing the current value
onChange - subscribe to change events
options - specify the options the user can select from
placeholder - change the text displayed when no option is selected
value - control the current value

See the props documentation for complete documentation on the props react-select supports.

Controllable Props

You can control the following props by providing values for them. If you don't, react-select will manage them for you.

value / onChange - specify the current value of the control
menuIsOpen / onMenuOpen / onMenuClose - control whether the menu is open
inputValue / onInputChange - control the value of the search input (changing this will update the available options)

If you don't provide these props, you can set the initial value of the state they control:

defaultValue - set the initial value of the control
defaultMenuIsOpen - set the initial open value of the menu
defaultInputValue - set the initial value of the search input

Methods

React-select exposes two public methods:

focus() - focus the control programatically
blur() - blur the control programatically

Customisation

Check the docs for more information on:

Thanks

Thank you to everyone who has contributed to this project. It's been a wild ride.

If you like React Select, you should follow me on twitter

Shout out to Joss Mackison, Charles Lee, Ben Conolly, Dave Brotherstone, Brian Vaughn, and the Atlassian Design System team ❤️

schalkventer/react-select