Skip to content

stratos-vetsos/react-selectrix

Repository files navigation

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.