react-datalist-input/README.md

Info

This package provides a single react component.

The component contains an input field with a drop down menu to pick a possible option based on the current input as a react component.

Following features describe and might distinguish the component from other npm packages that offer a similar react component:

• Hand over an array of options (items) with label and key properties
• Feel free to add additional properties to access those on selection within your callback function
• On selection the selected object will be passed to the callback function so you can access all properties of the selected item
• Define your own matching algorithm to restrict which options should be shown in the drop down menu based on the current user input
• Or do not pass an own matching algorithm and just use the default match function
• The current user input will be highlighted (bold) within each label in the drop down menu
• The callback function will be triggered only if the key property has changed since the last selection
• Selecting the same item twice in a row will trigger the callback function only once (on the first selection)

Have a look at w3schools.com to see how you can do the same thing with pure html, css, and js.

For more information about react and the ecosystem see this guide.

Check it out yourself

Have a look at this demo app using the react-datalist-input component.
The app is running on heroku for free, so I hope it is still up.

Feedback

Feel free to get inspired and more importantly please provide your feedback on structure and style. I'm more than happy to learn how to improve my code and architecture.

Installation

Installation via npm

npm install react-datalist-input --save

Basic Usage

import DataListInput from 'react-datalist-input';

/**
 * create your own match algorithm if you want to do so
 * @param currentInput String (the current user input)
 * @param item (one item of the items array)
 * @returns {boolean}
 */
matchCurrentInput = (currentInput, item) => {
    const yourLogic = item.someAdditionalValue;
    return (yourLogic.substr(0, currentInput.length).toUpperCase() === currentInput.toUpperCase());
};

/**
 * your callback function gets called if the user selects one option out of the drop down menu
 * @param selectedItem object (the selected item / option)
 * @returns {*}
 */
onSelect = (selectedItem) => {
   this.doSomething(selectedItem);
};

render() {
    // the array you want to pass to the react-data-list component
    // each element at least needs a key and a label
    const items = this.props.values.map((item, i) => {
        return {
            // what to show to the user
            label: item.id  + ": " + item.name,
            // key to identify the item within the array
            key: item.id,
            // feel free to add your own app logic to access those properties later on
            someAdditionalValue: item.someAdditionalValue,
        }
    });
    
    return(
        <div>
            <DataListInput placeholder={"Select an option from the drop down menu..."}
                          items={items} onSelect={this.onSelect} match={this.matchCurrentInput}/>
        </div>
);

Properties

items

• Required property!
• The array of options for the drop down menu.
  
• Every item inside the array needs to have following properties:
  • key : an id that identifies the item within the array
  • label: the label that will be shown in the drop down menu

onSelect

• Required property!
• The callback function that will be called if the user selects one item of the drop down menu.
• Gets only called if the item changes. Selecting the same item twice will only trigger the function once (the first time).
• Parameter: (selectedKey)
  • selectedKey: the Key Property of the item that the user selected

match

• Pass a match function as stated above for creating your own matching algorithm for the autocomplete functionality.

• Parameter: (currentInput, item)

  • currentInput: String, the current user input typed into the input field
  • item: Object, the item of the items array (with key and label properties)

• Default:

/**
 * default function for matching the current input value (needle) and the values of the items array
 * @param currentInput String (the current user input)
 * @param item (one item of the items array)
 * @returns {boolean}
 */
match = (currentInput, item) => {
    return item.label.substr(0, currentInput.length).toUpperCase() === currentInput.toUpperCase();
};

placeholder

• The placeholder that will be shown inside the input field.
• Default is an empty string