React-Select
The Select control for React. Initially built for use in KeystoneJS.
See react-select.com for live demos and comprehensive docs.
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.
For the story behind this component, watch Jed's talk at React Conf 2019 - building React Select
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
Using an older version?
- v2 to v3 upgrade guide
- v1 to v2 upgrade guide
- React Select v1 documentation and examples are 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:`, this.state.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 mountsclassName- apply a className to the controlclassNamePrefix- apply classNames to inner elements with the given prefixisDisabled- disable the controlisMulti- allow the user to select multiple valuesisSearchable- allow the user to search for matching optionsname- generate an HTML input with this name, containing the current valueonChange- subscribe to change eventsoptions- specify the options the user can select fromplaceholder- change the text displayed when no option is selectednoOptionsMessage- ({ inputValue: string }) => string, null - Text to display when there are no optionsvalue- 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 controlmenuIsOpen/onMenuOpen/onMenuClose- control whether the menu is openinputValue/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 controldefaultMenuIsOpen- set the initial open value of the menudefaultInputValue- set the initial value of the search input
Methods
React-select exposes two public methods:
focus()- focus the control programaticallyblur()- blur the control programatically
Customisation
Check the docs for more information on:
- Customising the styles
- Using custom components
- Using the built-in animated components
- Creating an async select
- Allowing users to create new options
- Advanced use-cases
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 ❤️
License
MIT Licensed. Copyright (c) Jed Watson 2019.