diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..b7451a6b --- /dev/null +++ b/ISSUE_TEMPLATE.md @@ -0,0 +1,9 @@ +### Thanks for using react-select! + +If you are reporting an error please include a test case that demonstrates the issue you're reporting! +This is very helpful to maintainers in order to help us see the issue you're seeing. + +Here is a Plunker you can fork that has react-select loaded and supports JSX syntax: +https://plnkr.co/edit/HTmtER9AMNcPoWhXV707?p=preview + +You may also find the [online Babel tool](https://babeljs.io/repl/) quite helpful if you wish to use ES6/ES7 syntax not yet supported by the browser you are using. diff --git a/README.md b/README.md index 44f54737..df5012b6 100644 --- a/README.md +++ b/README.md @@ -37,11 +37,25 @@ The easiest way to use React-Select is to install it from NPM and include it in npm install react-select-plus --save ``` -You can also use the standalone build by including `dist/react-select.js` and `dist/react-select.css` in your page. If you use this, make sure you have already included the following dependencies: +At this point you can import react-select and its styles in your application as follows: -* [React](http://facebook.github.io/react/) -* [classNames](http://jedwatson.github.io/classnames/) -* [react-input-autosize](https://github.com/JedWatson/react-input-autosize) +```js +import Select from 'react-select-plus'; + +// Be sure to include styles at some point, probably during your bootstrapping +import 'react-select/dist/react-select-plus.css'; +``` + +You can also use the standalone build by including `react-select-plus.js` and `react-select-plus.css` in your page. (If you do this though you'll also need to include the dependencies.) For example: +```html + + + + + + + +``` ## Usage @@ -52,7 +66,7 @@ Options should be provided as an `Array` of `Object`s, each with a `value` and ` The `value` property of each option should be set to either a string or a number. -When the value is changed, `onChange(newValue, [selectedOptions])` will fire. +When the value is changed, `onChange(selectedValueOrValues)` will fire. ```javascript var Select = require('react-select-plus'); @@ -82,8 +96,7 @@ You can enable multi-value selection by setting `multi={true}`. In this mode: * The selected values are submitted in multiple `` fields, use `joinValues` to submit joined values in a single field instead * The values of the selected items are joined using the `delimiter` prop to create the input value when `joinValues` is true * A simple value, if provided, will be split using the `delimiter` prop -* The `onChange` event provides an array of the selected options as the second argument -* The first argument to `onChange` is always a string, regardless of whether the values of the selected options are numbers or strings +* The `onChange` event provides an array of selected options _or_ a comma-separated string of values (eg `"1,2,3"`) if `simpleValue` is true * By default, only options in the `options` array can be selected. Setting `allowCreate` to true allows new options to be created if they do not already exist. * By default, selected options can be cleared. To disable the possibility of clearing a particular option, add `clearableValue: false` to that option: ```javascript @@ -204,6 +217,12 @@ For multi-select inputs, when providing a custom `filterOptions` method, remembe The `menuRenderer` property can be used to override the default drop-down list of options. This should be done when the list is large (hundreds or thousands of items) for faster rendering. +Windowing libraries like [`react-virtualized`](https://github.com/bvaughn/react-virtualized) can then be used to more efficiently render the drop-down menu like so. +The easiest way to do this is with the [`react-virtualized-select`](https://github.com/bvaughn/react-virtualized-select/) HOC. +This component decorates a `Select` and uses the react-virtualized `VirtualScroll` component to render options. +Demo and documentation for this component are available [here](https://bvaughn.github.io/react-virtualized-select/). + +You can also specify your own custom renderer. The custom `menuRenderer` property accepts the following named parameters: | Parameter | Type | Description | @@ -215,37 +234,6 @@ The custom `menuRenderer` property accepts the following named parameters: | selectValue | `Function` | Callback to select a new option; receives the option as a parameter. | | valueArray | `Array` | Array of currently selected options. | -Windowing libraries like [`react-virtualized`](https://github.com/bvaughn/react-virtualized) can then be used to more efficiently render the drop-down menu like so: - -```js -menuRenderer({ focusedOption, focusOption, labelKey, options, selectValue, valueArray }) { - const focusedOptionIndex = options.indexOf(focusedOption); - const option = options[index]; - const isFocusedOption = option === focusedOption; - - return ( - ( -
focusOption(option)} - onClick={() => selectValue(option)} - > - {option[labelKey]} -
- )} - rowsCount={options.length} - scrollToIndex={focusedOptionIndex} - width={200} - /> - ) -} -``` - -Check out the demo site for a more complete example of this. - ### Updating input values with onInputChange You can manipulate the input using the onInputChange and returning a new value. @@ -270,6 +258,7 @@ function cleanInput(inputValue) { addLabelText | string | 'Add "{label}"?' | text to display when `allowCreate` is true allowCreate | bool | false | allow new options to be created in multi mode (displays an "Add \