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.
Have a look at w3schools.com to see how you can do something similar with pure html, css, and js. For more information about React and the ecosystem see this guide.
Demo
Check it out on my personal website!
Feedback
Feel free to get inspired and more importantly please provide your feedback on structure and style.
Using Gatsby or Next.js?
This component is not compatible with server-side rendering since it has css bundled with it.
I created a plain version of this package without css. Find more information here.
Versions
- Version 2.x.x serves a functional component using hooks
- Version 1.x.x serves a class component
The documentation below mainly applies for both versions but will be updated based on version 2.x.x updates in the future.
Changelog
Version 2.2.0
- update React peer-dependency version to 17.0.2
Version 2.1.0
Motivation: issue 23
Offer optional value prop, in case the user requires full control to change/clear the input value based on side effects
Changes:
- deprecates optional
initialValue
prop - introduces optional
value
prop instead (default undefined) - introduces optional
clearOnClickInput
prop (default false) - introduces optional
onClick
lifecycle method prop (default empty function)
Version 2.0.0
Changes:
- refactors component to functional component using hooks
- adds
useStateRef
to reduce re-renders and boost performance
Installation
Installation via npm
npm i react-datalist-input
Basic Usage
import React, { useState, useMemo, useCallback } from "react";
import DataListInput from "react-datalist-input";
const YourComponent = ({ myValues }) => {
const [item, setItem] = useState();
const onSelect = useCallback((selectedItem) => {
console.log("selectedItem", selectedItem);
}, []);
const items = useMemo(
() =>
myValues.map((oneItem) => ({
label: oneItem.name,
key: oneItem.id,
someAdditionalValue: oneItem.someAdditionalValue,
...oneItem,
})),
[myValues]
);
return (
<DataListInput
placeholder="Select an option from the drop down menu..."
items={items}
onSelect={onSelect}
/>
);
};
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 match function:
const match = (currentInput, item) =>
item.label.substr(0, currentInput.length).toUpperCase() ===
currentInput.toUpperCase();
- If you are looking to have the same behavior as the HTML element datalist, use a match function like follows:
const match = (currentInput, item) =>
item.label.toLowerCase().includes(currentInput.toLowerCase());
onDropdownOpen
- The callback function that will be called after opening the drop down menu.
- It will fire only once and not be called again after new input.
onDropdownClose
- The callback function that will be called after closing the drop down menu.
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 or filled with selected item?
- Default is false.
- ❗ This property does not work if the prop
value
is set, you have to use the lifecycle method onSelect
and set your value state on your own.
clearInputOnClick
- Should the input field be cleared on click or filled with selected item?
- Default is false.
- ❗ This property does not workif the prop
value
is set, you have to use the lifecycle method onClick
and set your value state on your own.
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.
value
initialValue
is deprecated, use value
insteadvalue
can be used to specify and override the value of the input field- For example,
value="hello world"
will print hello world
into the input field - Default is undefined
- ❗ If you want to clean the input field based on side effects use
value
of empty string. - ❗ Use
value
only if you want complete control over the value of the input field. react-datalist-input
will priotize whatever value is set over anything the user selects or has selected. If you use value
, you will have to update it on your own using the onClick
, onInput
, andonSelect
lifecycle methods. - ❗ Don't confuse this with a placeholder (see placerholder prop). This property sets the actual value of the input field.
- ❗ The flags
clearInputOnSelect
and clearInputOnClick
won't work and have to be implemented via the mentioned lifecycle methods.
The following useEffect
is used to decide if the component should update with the new value
property:
useEffect(() => {
const isValuePropSet = value !== undefined;
const isValueDifferent = currentInputRef.current !== value;
const isMatchingRunning = visible || isMatchingDebounced;
if (isValuePropSet && isValueDifferent && !isMatchingRunning) {
setCurrentInput(value);
}
}, [visible, isMatchingDebounced, value, setCurrentInput, currentInputRef]);
debounceTime
- Use
debounceTime
to define a debounce timeout time (in milliseconds) before the matching algorithm should be called - New user input will trigger a new call to the debounce step and will clear every unresolved timeout
- For example,
debounceTime={1000}
will call the matching algorithm one second after the last user input - This is useful if
items
is very large and/or the match
-algorithm is doing some heavier operations debounceTime
may improve the user experience by reducing lag times as it reduces the calls to the matching and rendering of the dropdown.- Be careful, using too much debounceTime will slow down the response time of this component.
- If you still have performance issues even when using a
debounceTime={3000}
or higher, you might want to consider using another package / user input instead. Think about a "search/look-up"-button next to your input field or even consider running the search functionality in a dedicated backend. - Default is zero which means no timeout/debouncing is used.
debounceLoader
- Only in use if debounceTime is set
- Of type node which can be anything that react can render and will be shown as a loading bar
- Default is string "loading...".
onInput
- The callback function that will be called whenever the user types into the input field
- Exposing this function supports use cases like resetting states on empty input field
- The callback will receive the
newValue
of type string from event.target.value
onClick
- The callback function that will be called whenever the user clicks the input field
- This callback is exposed so you can implement
clearOnClickInput
on your own if you pass the value
prop - The callback will receive the
currentInput
of type string based on clearOnClickInput
and the last user input