react-select

What is react-select?

The react-select npm package is a flexible and customizable select input control for React applications. It provides a powerful set of features that allow developers to create simple dropdowns, multi-selects, async data loading, and more, with a focus on accessibility and customizability.

What are react-select's main functionalities?

Basic Single Select

This feature allows you to create a basic single selection dropdown where a user can select one option from a predefined list.

{"import Select from 'react-select';\n\nconst options = [\n  { value: 'chocolate', label: 'Chocolate' },\n  { value: 'strawberry', label: 'Strawberry' },\n  { value: 'vanilla', label: 'Vanilla' }\n];\n\nconst MyComponent = () => (\n  <Select options={options} />\n);"}

Multi-Select

This feature enables users to select multiple options from the dropdown. It is useful for fields that require more than one selection.

{"import Select from 'react-select';\n\nconst options = [\n  { value: 'chocolate', label: 'Chocolate' },\n  { value: 'strawberry', label: 'Strawberry' },\n  { value: 'vanilla', label: 'Vanilla' }\n];\n\nconst MyComponent = () => (\n  <Select isMulti options={options} />\n);"}

Asynchronous Loading

This feature allows for loading options asynchronously, which is useful when the options are not available at initial render time or need to be fetched based on user input.

{"import Select from 'react-select';\nimport AsyncSelect from 'react-select/async';\n\nconst loadOptions = (inputValue, callback) => {\n  setTimeout(() => {\n    callback(filterOptions(inputValue));\n  }, 1000);\n};\n\nconst MyComponent = () => (\n  <AsyncSelect loadOptions={loadOptions} />\n);"}

Creatable Select

This feature allows users to create a new option on the fly if the option they are looking for is not available in the list.

{"import CreatableSelect from 'react-select/creatable';\n\nconst options = [\n  { value: 'chocolate', label: 'Chocolate' },\n  { value: 'strawberry', label: 'Strawberry' },\n  { value: 'vanilla', label: 'Vanilla' }\n];\n\nconst MyComponent = () => (\n  <CreatableSelect isMulti options={options} />\n);"}

Other packages similar to react-select

downshift

Downshift is a set of primitives to build simple, flexible, WAI-ARIA compliant enhanced input React components. Its major focus is on flexibility and providing the building blocks for creating custom dropdown components. It is more low-level than react-select and requires more boilerplate to achieve similar functionality.

react-autosuggest

React-autosuggest is a WAI-ARIA compliant React autosuggest component that provides a simple yet customizable input field with suggestions. While it is similar to react-select in providing suggestions, it does not offer as many features out of the box, such as multi-select or async options.

antd

Ant Design (antd) is a design system with a set of high-quality React components, one of which is a Select component. It offers a comprehensive suite of features similar to react-select but is part of a larger framework, which might be more than needed if only a select component is required.

README

React-Select

A Select control built with and for React, initially being developed for use in KeystoneJS.

Demo & Examples

Live demo: jedwatson.github.io/react-select

To build the examples locally, run:

npm install
gulp dev

Then open localhost:8000 in a browser.

Project Status

This is currently a work in progress.

It's loosely based on Selectize (in terms of behaviour and user expereience) and React-Autocomplete (as a native React Combobox implemenation), as well as other select controls including Chosen and Select2.

TODO:

• CSS Styles and theme support (working, could be improved)
• Documentation website (currently just examples)
• Custom options rendering

Installation

The easiest way to use React-Select is to install it from NPM and include it in your own React build process (using Browserify, etc).

You can also use the standalone build by including dist/select.js and dist/default.css in your page. If you use this, make sure you have already included React and Underscore.

npm install react-select --save

Usage

React-Select generates a hidden text field containing the selected value, so you can submit it as part of a standard form. You can also listen for changes with the onChange event property.

Options should be provided as an Array of Objects, each with a value and label property for rendering and searching.

When the value is changed, onChange(newValue, [selectedOptions]) will fire.

var Select = require('react-select');

var options = [
	{ value: 'one', label: 'One' },
	{ value: 'two', label: 'Two' }
];

function logChange(val) {
	console.log("Selected: " + val);
}

<Select
	name="form-field-name"
	value="one"
	options={options}
/>

Multiselect options

You can enable multi-value selection by setting multi="true". In this mode:

• Selected options will be removed from the dropdown menu
• The values of the selected items are joined using the delimiter property to create the input value
• A simple value, if provided, will be split using the delimiter property
• The onChange event provides an array of the selected options as the second argument

Async options

If you want to load options asynchronously, instead of providing an options Array, provide a asyncOptions Function.

The function takes two arguments String input, Function callbackand will be called when the input text is changed.

When your async process finishes getting the options, pass them to callback(err, data) in a Object { options: [] }.

The select control will intelligently cache options for input strings that have already been fetched. Async options will still be filtered like the normal options array, so if your async process would only return a smaller set of results for a more specific query, also pass complete: true in the callback object.

Unless you specify the property autoload="false" the control will automatically load the default set of options (i.e. for input: '') when it is mounted.

var Select = require('react-select');

var getOptions = function(input, callback) {
	setTimeout(function() {
		callback(null, {
			options: [
				{ value: 'one', label: 'One' },
				{ value: 'two', label: 'Two' }
			],
			complete: true
		});
	}, 500);
};

<Select
	name="form-field-name"
	value="one"
	asyncOptions={getOptions}
/>

Filtering options

You can control how options are filtered with the following properties:

• matchPos: "start" or "any": whether to match the text entered at the start or any position in the option value
• matchProp: "label", "value" or "any": whether to match the value, label or both values of each option when filtering

Both properties default to "any".

Advanced filters

You can also completely replace the method used to filter either a single option, or the entire options array (allowing custom sort mechanisms, etc.)

• filterOption: function(Object option, String filter) returns Boolean. Will override matchPos and matchProp options.
• filterOptions: function(Array options, String filter, Array currentValues) returns Array filteredOptions. Will override filterOption, matchPos and matchProp options.

For multi-select inputs, when providing a custom filterOptions method, remember to exclude current values from the returned array of options.

License

MIT Licensed. Copyright (c) Jed Watson 2014.