yuters / react-selectize

React Selectize

ReactSelectize is a stateless Select component for ReactJS, that provides a platform for the more developer friendly SimpleSelect & MultiSelect components.

Both SimpleSelect & MultiSelect have been designed to work as drop in replacement for the built-in React.DOM.Select component.

styles & features inspired by React Select & Selectize.

DEMO / Examples: furqanZafar.github.io/react-selectize

• Changelog (last updated on 21st January 2016)
• API Reference

Motivation

• existing components do not behave like built-in React.DOM.* components.
• existing components synchronize props with state an anti pattern, which makes them prone to bugs & difficult for contributers to push new features without breaking something else.
• more features.

Features

• Drop in replacement for React.DOM.Select
• Stateless, therefore extremely flexible & extensible
• Clean and compact API fully documented on GitHub
• Multiselect support
• Option groups
• Custom filtering & option object
• Search highlighting
• Custom option & value rendering
• Animated dropdown
• Remote data loading
• Tagging or item creation
• Restore on backspace
• Editable value
• Caret between items
• Customizable dropdown direction
• Mark options as unselectable
• Disable selected values
• Customizable styles, comes with Stylus files

Install

npm install react-selectize

Usage (livescript)

{create-factory}:React = require \react
{SimpleSelect, MultiSelect, ReactSelectize} = require \react-selectize
SimpleSelect = create-factory SimpleSelect
MultiSelect = create-factory MultiSelect
.
.
.
SimpleSelect do     
    placeholder: 'Select a fruit'
    options: <[apple mango orange banana]> |> map ~> label: it, value: it
    on-value-change: (value, callback) ~>
        alert value
        callback!
.
.
.
MultiSelect do
    placeholder: 'Select fruits'
    options: <[apple mango orange banana]> |> map ~> label: it, value: it
    on-values-change: (values, callback) ~>
        alert values
        callback!

Usage (jsx)

React = require("react");
ReactSelectize = require("react-selectize");
SimpleSelect = ReactSelectize.SimpleSelect;
MultiSelect = ReactSelectize.MultiSelect;
.
.
.
<SimpleSelect
    placeholder = "Select a fruit"
    onValueChange = {function(value, callback){
        alert(value);
        callback();
    }}
>
    <option value = "apple">apple</option>
    <option value = "mango">mango</option>
    <option value = "orange">orange</option>
    <option value = "banana">banana</option>
</SimpleSelect>
.
.
.
// Note: options can be passed as props as well, for example
<MultiSelect
    placeholder = "Select fruits"
    options = ["apple", "mango", "orange", "banana"].map(function(fruit){
        return {label: fruit, value: fruit};
    });
    onValuesChange = {function(values, callback){
        alert(values);
        callback();
    }}
/>

Usage (stylus)

to include the default styles add the following import statement to your stylus file:

@import 'node_modules/react-selectize/src/index.css'

Gotchas

• the default structure of an option object is {label: String, value :: a} where a implies that value property can be of any equatable type

• SimpleSelect notifies change via onValueChange prop whereas MultiSelect notifies change via onValuesChange prop

• the onValueChange callback for SimpleSelect is passed 2 parameters. the selected option object (instead of the value property of the option object) and a callback

• the onValuesChange callback for MultiSelect is passed 2 parameters an Array of selected option objects (instead of a collection of the value properties or a comma separated string of value properties) and a callback

• all the on*Change functions receive a callback as the final parameter, which MUST always be invoked, for example when using state for the value prop of SimpleSelect the onValueChange callback implementation would look like this:

value = {{label: "apple", value: "apple"}}
onValueChange = {function(value, callback){
    self.setState(value, callback);
}}

when relying on the components internal state for managing the value:

onValueChange = {function(value, callback){
    console.log(value);
    callback(); // must invoke callback    
}}

• when using custom option object, you should implement the uid function which accepts an option object and returns a unique id, for example:

// assuming the type of our option object is:
// {firstName :: String, lastName :: String, age :: Int}
uid = {function(item){
    return item.firstName + item.lastName;    
}}

the uid function is used internally for performance optimization.

Development

• npm install
• gulp
• visit localhost:8000
• npm test , npm run coverage for unit tests & coverage
• for production build/test run MINIFY=true gulp