component that quacks like an HTML
<input> but which includes a selectable list
of suggestions for filling in its value.
As you type text into the input field, a list of suggestions will be displayed in a selectable overlay just below. The suggestions are an array of strings given to the component as a prop and are compared to the ever-changing query string that you are typing. The "closer" a suggestion is to what you have typed, the higher in the list it will appear.
npm install suggestible-input --save
Use SuggestibleInput where you would use a regular
<input> tag in your React
app. It will behave as you would expect an
<input> to behave with the added
bonus of giving users the ability to complete their text input from a list of
The simplest way of using it is to require it, and then render it by passing it an array of strings (the suggestions). See the "basic" demo in the examples folder.
var SuggestibleInput = ;var suggestions ='Toronto''Montreal''Ottawa''Vancouver''Edmonton''Calgary';<SuggestibleInput suggestions=suggestions />
More advanced usage involves passing an array of objects into the component (as opposed to plain strings). This allows you some additional control over the suggestion list output such as assigning custom classes to particular suggestions, as well as including extra data to pass along with the suggestion.
When defining suggestions as objects, each suggestion must contain a
property. Optionally, you may pass a
class property which is a simple string
value that will be passed into the
<li> element's class which contains the
suggestion in the drop-down list (this can be one or more class names just as
you would define them in plain HTML). Finally, you may also add any additional,
custom, properties you like to the object. These properties can then be accessed
onChoose() callback so that you can associate custom data with each
The following example demonstrates how to construct an array of suggestions as objects, as well as how to use some of the other props to customize how the component is rendered. See the "objects" demo in the examples folder.
var SuggestibleInput = ;var suggestions =name: 'Toronto' class: 'my-custom-class' customProperty: 'my-custom-property'name: 'Montreal'name: 'Vancouver'name: 'Ottawa' class: 'my-custom-class'name: 'Edmonton' class: 'my-custom-class'name: 'Calgary' customProperty: 'my-custom-property';<SuggestibleInputsuggestions=suggestionsmaxSuggestions=5placeholder="Find canadian cities..."clearOnSelect=true />
You can style the component any way you like by simply implementing the following CSS classes and elements.
|.suggestible-input||The outer container of the whole component.|
|.suggestible-input > input||The actual input element used for entering text.|
|.suggestible-input-clear||A button used to clear the value of the input. It has no content itself and is intended to be given a background-image for graphics.|
|.suggestible-input-suggestions||A container that wraps the list of suggestions + a background overlay.|
|.suggestible-input-suggestions > ul||The list of suggestions.|
|.suggestible-input-suggestions > ul > li||An individual suggestion in the list.|
|.suggestible-input-bg||A background overlay that can be used to block, or dim, anything underneath the component while the suggestions are being shown.|
The basic HTML markup structure looks like this when it is output to the DOM:
First SuggestionSecond SuggestionThird Suggestion
In this code snippet,
.my-custom-class is an example of what a custom class would
look like in the markup if it were passed to SuggestibleInput using a list of
suggestion objects, described under "advanced" usage above.
There are examples in
examples/dist/ that you can use as a starting point.
How it works
A combination of filters get used to shorten the list of suggestions and sort them based on a heuristic relevance.
Find a subset of suggestions that match what you've typed based on a simple algorithm which finds suggestion strings that match your query string in terms of containing the characters of the query string, in the order that they appear (not necessarily in sequence).
Rank each suggestion in the subset based on how different it is from the query string (that is, how many edits it would take to change the suggestion into the query string).
Sort the subset list based on their rankings.
Cut off the list at the user-defined maximum (or 10, by default).
|value||string||''||Used to set the initial value of the input.|
|suggestions||array||||An array of strings/objects used as the source of the suggestions that are displayed.|
|maxSuggestions||number||10||The maximum number of suggestions to display at one time.|
|placeholder||string||''||The value of the input's placeholder, shown when there is no value.|
|clearOnSelect||boolean||false||Whether or not to clear the input's value when selecting a suggestion.|
|onChange||function||null||Used to hook into onChange events of the input.|
|onKeyDown||function||null||Used to hook into onKeyDown events of the input.|
|onChoose||function||null||Used to hook into onChoose events when selecting a suggestion from the dropdown.|
React >= 0.14
The initial pattern matching algorithm is based on fuzzysearch.
The "x" icon used in the examples is from ionicons.