React Selectrix
A beautiful, materialized, easy to use and flexible React Select replacement
Demo
Check out the demo and use examples here!
Installing
npm i --save-dev react-selectrix
Documentation
https://github.com/stratos-vetsos/react-selectrix/
Import to your project
import Selectrix from "react-selectrix";
Basic Example
<Selectrix
multiple={true}
materialize={true}
options={[
{
key: "javascript",
label: "Javascript"
},
{
key: "go",
label: "Go"
},
{
key: "ruby",
label: "Ruby On Rails"
},
{
key: "php",
label: "PHP"
}
]}
onChange={ value => console.log( value ) }
/>Props
| Name | Type | Default Value | Description |
|---|---|---|---|
| options | array | [] | An array of the available options ( Objects with "key", "label" pairs and optionally "disabled" property ). |
| multiple | boolean | false | Whether the Select supports multiple values. |
| searchable | boolean | true | Whether the Select is searchable. |
| noResultsMessage | string | No results match | The message of the no results match. |
| materialize | boolean | true | Whether the style of the Select should be Materialized or default. |
| defaultValue | boolean / array / string | false | If you have preselected values use this property. Use an array of option keys for multiple selections, or key as a string for single selection. |
| checkBoxes | boolean | false | Set this to true if you want to render Checkboxes instead of list items. |
| height | number | 190 | The height of the dropdown. |
| placeHolderInside | boolean | false | If the placeholder should be an option. |
| placeholder | string | Please Select | The placeholder of the Select. |
| isOpen | boolean | false | If the Select should be rendered open. |
| arrow | boolean | true | Whether to show an arrow on Select's header. |
| disabled | boolean | false | Whether the Select should be disabled. |
| customScrollbar | boolean | false | A custom scrollbar ( only for Chrome ) |
| stayOpen | boolean | false | If the Select should stay open or not. |
| commaSeperated | boolean | false | If you want the selected values to be a comma seperated string, turn this to "true". ( Available only with multiple prop set to "true". ) |
| singleLine | boolean | false | Where the selected values ( Select's Header ) should be contained to one line. |
| lifo | boolean | false | Last In First Out Mode. The user's last selection, goes first. ( Available only with multiple prop set to "true". ) |
| searchIndex | boolean | true | Enable search by both Index and Value fields |
| selectAllButton | boolean | false | Whether a "select all button" should be visible on Select's header. |
| isDropDown | boolean | true | Set this to true if you want to use the Select as a Dropdown. When you select an option, the Select collapses and the header continue to have the placeholder as a value. |
| tags | boolean | false | Whether to support custom tags. |
| customKeys | object / boolean | false | Pass an object to change the default option keys ( key, label ). Example Syntax: { key: "url", label: "title" } , to change the key to "url" and the label to "title". |
| ajax | boolean / object | false | Whether to enable ajax. The library supports asynchronous calls through fetch API. Available default properties of ajax object: { url: '', headers: {}, debounce: 200, fetchOnSearch: false, q: "", nestedKey: false, searchPrompt: true, minLength: 1 }. You can find details for all the ajax object properties, in the next section and in our demo page. |
| onRenderOption | function / boolean | false | Use this function to render custom option items |
| onRenderSelection | function / boolean | false | Use this function to render custom selected items |
| onChange | function | undefined | Use this callback to catch Select's change trigger. |
| onOpen | function | undefined | Use this callback to catch Select's open trigger. |
| onClose | function | undefined | Use this callback to catch Select's close trigger. |
Ajax prop - breakdown
| Name | Type | Default Value | Description |
|---|---|---|---|
| url | string | '' | The url which the Select going to fetch the available options. |
| headers | object | {} | Pass any headers you want to fetch api. |
| debounce | number | 200 | The debounce of the ajax calls in milliseconds. |
| fetchOnSearch | boolean | false | Whether you don't want to have the options prepopulated, when the Select opens, but you want to query them based on user's search value. |
| q | string | '' | This property goes alongside with fetchOnSearch property, setted to "true". Depending the REST API providing you with options, you have to change this value accordingly. e.g. "&search={q}". Wherever you use the pseudo variable {q}, the user's search query will injected in the final request. |
| nestedKey | string / boolean | false | If your REST API returns the actual data in a deeper level, inside a nested key, let's say "articles", set nestedKey to "articles". |
| searchPrompt | boolean | true | This property goes alongside with fetchOnSearch property and indicates the user how many more characters should type, before the ajax search will happen. |
| minLength | number | 1 | This property goes alongside with fetchOnSearch property and searchPrompt setted to "true". It is the min length of characters the user should type, before the ajax call search takes place. |
Callbacks - breakdown
| Name | Arguments | Description |
|---|---|---|
| onChange | value | The selected object if the Select is single and an array of objects if the Select is multiple. |
| onRenderOption | option, index | The option which is going to be rendered and it's corresponding index. |
| onRenderSelection | selected, settings, deselect | The selected object, the Select's settings and a callback function to use for deselection. |
| onOpen | N/A | |
| onClose | N/A |
Ajax Example
Many thanks to newsapi.org for their great api. Check this example in action, in our demo page.
<Selectrix
customKeys={{
key: "url",
label: "title"
}}
ajax={{
url: "https://newsapi.org/v2/everything?q=bitcoin&sortBy=publishedAt&apiKey=9342a9a707ca49c4b2da34e9ea238ea6",
nestedKey: "articles"
}}
/>Ajax Example with fetchOnSearch
Check this example in action, in our demo page.
<Selectrix
multiple={true}
stayOpen={true}
materialize={true}
customKeys={{
key: "url",
label: "title"
}}
ajax={{
url: "https://newsapi.org/v2/top-headlines?apiKey=9342a9a707ca49c4b2da34e9ea238ea6",
fetchOnSearch: true,
q: "&q={q}",
nestedKey: "articles",
minLength: 3,
debounce: 300
}}
/>Tags Example
Check this example in action, in our demo page.
<Selectrix
multiple={true}
materialize={true}
tags={true}
options={[
{
key: "hotdog",
label: "Hot Dog"
},
{
key: "pizza",
label: "Pizza"
}
]}
onChange={ value => console.log( value ) }
/>Custom Render Example
Check this example in action, in our demo page.
<Selectrix
multiple={true}
materialize={true}
options={[
{
key: "javascript",
label: "Javascript"
},
{
key: "go",
label: "Go"
},
{
key: "ruby",
label: "Ruby On Rails"
},
{
key: "php",
label: "PHP"
}
]}
onRenderOption={onRenderOption}
onRenderSelection={onRenderSelection}
onChange={ value => console.log( value ) }
/>
const onRenderOption = ( option, index ) => (
<span><i className="fa fa-laptop"></i>{ option.label }</span>
)
const onRenderSelection = ( selected, settings, deselect ) => (
<span style={{ marginRight: 10, border: "1px solid #eee", padding: 5 }}>
{ selected.label }
<i style={{ paddingLeft: 5, cursor: "pointer" }} onClick={ deselect } className="fa fa-window-close"></i>
</span>
)License
MIT Licensed. Stratos Vetsos.
Contributions
Contributions are more than welcome. Run npm install && npm start on master and you are good to go! The CONTRIBUTING.md is going to be published soon.