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 item will be passed to the callback function
• 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

itemClassName

• Additional classes to style each input field in the dropdown menu.
• Default is an empty string
• Removes the default styling if set

activeItemClassName

• Additional classes to style the active input field.
• Default is an empty string
• Removes the default styling if set

inputClassName

• Additional classes to style the input field.
• Default is an empty string
• Removes the default styling if set

dropdownClassName

• Additional classes to style the dropdown box.
• Default is an empty string
• Adds on the required styling (e.g. position:absolute)
• Removes the default styling if set

requiredInputLength

• Number to specify the threshold until when the dropdown menu should appear.
• Example requiredInputLength=3, only if the user input is longer than 2 characters, the dropdown menu will appear.
• Default is zero.

clearInputOnSelect

• Should the input field be cleared on select on filled with selected item?
• Default is false.

suppressReselect

• If suppressReselect is set to false, selecting the same item again, it will trigger another onSelect callback call.
• Default is true.

dropDownLength

• Only display the first dropDownLength matches in the dropdown. Useful if the array is really big.
• Number to specify max length of drop down.
• Default is Infinity.

initialValue

• Specigy an initial value for the input field.
• For example, initialValue={'hello world'} will print hello world into the input field on first render.
• Default is empty string.