You can literally customize any piece of the component using listRenderer, optionRenderer, selectedBlockRenderer, iconRenderer and others.
We have various HOC's that may help you to integrate with your existing application.
All of our classes are extendable with CSS modules. Take a look at list of them.
Yes, yes! You can inspect dropdown list with help of DevTools. You know what I'm talking about, right?
Still not sure? We have a lot of other cool features. Take a look at our examples.
- Installation
- Usage
- Examples
- HOC
- Properties:
- options: Array
- value: Any
- multiple: Bool
- searchable: Bool
- virtualized: Bool
- onChange: Function
- onSearch: Function
- onAddNewItem: Bool
- selectedValueRenderer: Function
- selectedBlockRenderer: Function
- optionRenderer: Function
- listRenderer: Function
- iconRenderer: Function
- noItemsFound: Bool | String | Function
- addNewItem: Bool | String | Function
- isOpened: Bool
- beforeOpen: Function
- beforeClose: Function
- onOpen: Function
- onClose: Function
- searchClearOnClose: Bool
- listMaxHeight: Number
- listHeight: Number
- optionHeight: Number | Function
- listPosition: String
- getWrapper: Function
- boundaryMargin: Number
- forbidPhantomSelection: Bool
- s: Object
npm i react-select-me --save
import Select from 'react-select-me';
// IMPORTANT If you want to provide default styles you have to import them
import 'react-select-me/lib/ReactSelectMe.css';
const options = [
{ value: 1, label: 'Label 1' },
{ value: 2, label: 'Label 2' },
];
export default class App extends React.Component {
constructor(props) {
super(props);
this.state = { value: null };
this.onChange = this.onChange.bind(this);
}
onChange(value) {
this.setState({ value });
}
render() {
return <Select options={options} value={this.state.value} onChange={this.onChange} />;
}
}http://maslianok.github.io/react-select-me/
-
Clone the repo
git clone [email protected]:maslianok/react-select-me.git -
Go to the directory
cd react-select-me -
Install dependencies
npm i -
Run demo app
npm start -
Open
localhost:3000in your browser
We've extracted some key features into separate HOCs to keep the main library as small as possible
Uses virtualized list to render dropdown options. It allows you to render huge lists without affecting the page performance.
import Select from 'react-select-me';
import makeVirtualized from 'react-select-me/lib/hoc/makeVirtualized';
const VirtualizedSelect = makeVirtualized(Select);
// now you can use the VirtualizedSelect component as usual
// ...
<VirtualizedSelect options={options} value={this.state.value} onChange={this.onChange} />;
// ...Integrates with immutable-js which allows you to pass immutable structures as component's props.
import Select from 'react-select-me';
import makeImmutable from 'react-select-me/lib/hoc/makeImmutable';
const ImmutableSelect = makeImmutable(Select);
// now you can pass immutable data as options
// ...
<ImmutableSelect options={options} value={this.state.value} onChange={this.onChange} />;
// ...Description: list of dropdown options
Default: undefined
Examples:
- List of primitives:
[1, 2] - List of objects:
[{value: 1, label: 'Label 1'}, {value: 2, label: 'Label 2'}]
Description: selected value / values
Default: undefined
Examples:
- Primitive:
1 - Object:
{value: 1, label: 'Label 1'} - Array of primitives for multiselect:
[1, 2] - Array of objects for multiselect:
[{value: 1, label: 'Label 1'}, {value: 2, label: 'Label 2'}]
Description: multi-value dropdown
Default: false
Description: ability to search / filter options. onSearch function will be called
Default: false
Description: partly render list options using react-virtualized. Huge time to render boost on large datasets. You have to set optionHeight property if your option height differs from default.
Default: false
Description: parse data as immutable lists. When this property set to true you have to provide options and value as immutable objects.
Default: false
Description: onChange callback. Return false to leave dropdown opened.
Default: undefined
Arguments:
value: Array|Object|String|Number: selected option (or array of options for multi select)
Example:
onChange(value) {
// handle new value
}Description: onSearch callback. Calls on every search input change. You have to process search string inside this function and filter your options based on your needs.
Default: undefined
Arguments:
search: String: search string
Example:
const options = [
{ value: 1, label: 'Label 1' },
{ value: 2, label: 'Label 2' },
];
export default class App extends React.Component {
constructor(props) {
super(props);
this.state = { options };
this.onSearch = this.onSearch.bind(this);
}
onSearch(searchString) {
this.setState({
options: options.filter(o => o.label.indexOf(searchString) > -1)
});
}
render() {
return (
<Select
searchable
options={this.state.options}
onSearch={this.onSearch}
...
/>
);
}
}Description: callback to handle click on the 'Add new item' option
Default: undefined
Arguments:
search: String: search string
Description: function to render selected value
Default: undefined
Arguments:
option: Object|String|Number: option to renderonRemove: Function: default function to remove value
Example:
selectedValueRenderer(option, onRemove) {
return <div style={{color: 'red'}}>{option.label}</div>;
}Description: the function to render the whole block with selected options
Default: undefined
Arguments:
selectedOptions: Array: the options to be rendered. These are the selected options. You must render them inside theselectedBlockRendererfunctiononRemove: Function: is the function that must be triggered on a certain option when you want to remove it. For example, you receive [1,2,3,4] as theselectedOptions, so you have to callonRemove(1)in order to deselect option 1selectedValueRenderer: Function: is the default value renderer. The library uses this function in order to render every single selected option. Something likeselectedOptions.map(option => selectedValueRenderer(option)). You can use it or skip and implement your own value renderer.searchInputRenderer: Function: is the default function to render search input. The same as above: use it or implement you own logic
Example:
selectedBlockRenderer(selectedOptions, onRemove) {
return <div>{selectedOptions.map(option => option.label).join(', ')}</div>;
}Description: function to render custom options
Default: undefined
Arguments:
option: Object|String|Number: option to renderselectedOptions: Array: currently selected options
Example:
optionRenderer(option, selectedOptions) {
return <div style={{color: 'red'}}>{option.label}</div>;
}Description: function to render the list
Arguments:
options: Array: list of optionsselectedOptions: Array: currently selected optionsoptionRenderer: Function: default option rendereronChange: Function: default onChange callbackonToggleList: Function: toggle list visibility
Example:
- Simple
listRenderer(options, selectedOptions, optionRenderer) {
return <ul>{options.map(option => optionRenderer(option, selectedOptions))}</ul>;
}- Advanced
listRenderer(options, selectedOptions, optionRenderer, onChange, onToggle) {
return (
<div className={s.listWrapper}>
<div className={s.options}>
{options.map(option => (
<div className={s.option} onClick={onChange(option)} key={option.value}>
<div style={{backgroundColor: option.color}} className={s.circle}></div>
<div>{option.label}</div>
</div>
))}
</div>
<div className={s.actions>
<button className={s.btn} onClick={onToggle}>Save</button>
</div>
</div>
);
}Description: function to render custom icon.
Default: undefined
Arguments:
isOpened: Bool: whether the list opened
Example:
iconRenderer(isOpened) {
return <i className={isOpened ? 'icon-open' : 'icon-close'} />;
}Description: Bool: whether to display 'No items found' option or not. String: 'No items found' label. Function: 'No items found' renderer
Default: true
Example:
noItemsFound() {
return <div className="my-awesome-class">No items found</div>;
}Description: Bool: whether to display 'Add new item' option or not. String: 'Add new item' label. Function: 'Add new item' renderer. You must handle onClick event via onAddNewItem callback or your own callback in case of custom renderer. Note: for the 'Add new item' option to display, searchable must be true and options must be empty.
Default: false
Example:
addNewItem(search) {
return <div className="my-awesome-class" onClick={this.addNewItemToDropdownOptions}>{`Add '${search}'`}</div>;
}Description: setting this property makes open / close functionality uncontrollable. It always opened when isOpened === true and always closed when isOpened === false. Setting this property to undefined returns component to the usual behaviour.
Default: undefined
Description: before open handler. Return false to leave dropdown closed.
Default: undefined
Arguments:
event: Object: event
Description: before close event. Return false to leave dropdown opened.
Default: undefined
Description: handler for when the menu opens
Default: undefined
Description: handler for when the menu closes
Default: undefined
Description: whether to clear the input on close or not
Default: true
Description: Dropdown list max height in pixels.
Default: 400
Description: when you set this property the list will always have the constant height despite options length and available space. You have to set this property only when you are creating something like horizontally scrolling lists or some other weird lists :) Otherwise, you probably need to listMaxHeight.
Description: option height. This property has to be set for virtualized lists, because react-virtualized has to know total options height to correctly display scroll. It also used to calculate direction to open the list (in case of direction="auto").
Default: 40
Description: Dropdown list position.
Default: auto
Available values:
top: expand to topbottom: expand to bottomauto: auto detection based onwrapperelement
Description: Function to get wrapper element. Commonly you have to set this parameter if any of component's parents has overflow: hidden property. This parameter affects to listMaxHeight and listPosition properties.
Description: the minimal distance between screen / wrapper boundaries and dropdown list.
Default: 6
Description: doesn't select a value option if it doesn't exist in options array
Default: false
Description: component classNames.
List of supported classes:
{
// wrapper
dd__wrapper,
// applied to multi select
dd__multi,
// applied to single select
dd__single,
// applied when dropdown opened
dd__opened,
// applied when dropdown has error property
dd__error,
// disabled
dd_disabled: classType,
// selected block class
dd__selectControl,
// selected values wrapper class
dd__selected,
// placeholder class
dd__placeholder,
// selected option class
dd__selectedItem,
// icon to remove selected value class
dd__crossIcon,
// list class
dd__list,
// virtualized list class
dd__listVirtualized,
// applied when select opens to bottom
dd__openTobottom,
// applied when select opens to top
dd__openTotop,
// dropdown option
dd__option,
// virtualized option class
dd__optionVirtualized,
// selected dropdown option
dd__selectedOption,
}Examples:
- If you are using css modules you can import default styles directly to the component:
import Select from 'react-select-me';
import s from 'react-select-me/src/ReactSelectMe.css';
...
<Select s={s} {...otherProps} />- If you want to customize any element with help of your own classes
const classNames = {
// usual class names
dd__wrapper: 'my-super-class',
// or even with css modules
dd__selectedOption: s.mySuperSelectedOption,
};
<Select s={classNames} {...otherProps} />;