Progressive and customizable autocomplete component
Browser support includes every sane browser and IE7+.
You can see a live demo here.
I needed a fast, easy to use, and reliable autocomplete library. The ones I stumbled upon were too bloated, too opinionated, or provided an unfriendly human experience.
The goal is to produce a framework-agnostic autocomplete that is easily integrated into your favorite MVC framework, that doesn't translate into a significant addition to your codebase, and that's enjoyable to work with. Horsey shares the modular design philosophy of Rome, the datetime picker. Furthermore, it plays well with Insignia, the tag editor component, and pretty much any other well-delimited component out there.
- Small and focused
- Natural keyboard navigation
- Progressively enhanced
- Extensive browser support
- Fuzzy searching
- Supports
<input>and<textarea>elements
You can get it on npm.
npm install horsey --saveOr bower, too.
bower install horsey --saveEntry point is horsey(el, options). Configuration options are detailed below. This method returns a small API into the horsey autocomplete list instance. You can also find existing horsey instances using horsey.find.
An array containing a list of suggestions to be presented to the user. Each suggestion can be either a string or an object. If an object is used, the text property will be used for displaying the suggestion and the value property will be used when a suggestion is selected.
Alternatively, the suggestions can be a function. In this case, the function will be called when the input is focused, and expected to return a list of suggestions through a callback.
The example below would create an instance with a predefined set of suggestions.
horsey(el, {
suggestions: ['sports', 'drama', 'romantic comedy', 'science fiction', 'thriller']
});Here's how you would lazy load your suggestions, except, you know, using actual AJAX calls. Note that this method is called a single time.
horsey(el, {
suggestions: function (done) {
setTimeout(function () {
done(['sports', 'drama', 'romantic comedy', 'science fiction', 'thriller']);
}, 2000);
}
});Allows you to hide suggestions based on user input. The default implementation uses the fuzzysearch module to discard suggestions that don't contain anything similar to the user input.
function defaultFilter (q, suggestion) {
return fuzzysearch(q, getText(suggestion)) || fuzzysearch(q, getValue(suggestion));
}The example below would always display every suggestion, except when the user input looks like 'seahawks/managers', in which case it would only return suggestions matching the 'seahawks' team.
horsey(el, {
filter: function (q, suggestion) {
var parts = q.split('/');
return parts.length === 1 ? true : suggestion.team === parts[0];
}
});A function that returns the textual representation to be displayed on the suggestion list. The result of getText is also used when filtering under the default implementation.
function defaultGetText (suggestion) {
return typeof suggestion === 'string' ? suggestion : suggestion.text;
}The example below would return a model's displayName for convenience.
horsey(el, {
getText: function (suggestion) {
return suggestion.displayName;
}
});A function that returns the value to be given to the el when a suggestion is selected.
function defaultGetValue (suggestion) {
return typeof suggestion === 'string' ? suggestion : suggestion.value;
}The example below would return a model's username for convenience.
horsey(el, {
getValue: function (suggestion) {
return suggestion.username;
}
});A function that gets called when an option has been selected on the autocomplete.
function defaultSetter (value) {
el.value = value;
}The example below would append values instead of overwriting them.
horsey(el, {
set: function (value) {
el.value += value + ', ';
}
});Hides the autocomplete list whenever something other than the el or any child of the autocomplete's <ul> element is clicked. Defaults to true.
Hides the autocomplete list whenever something other than the el or any child of the autocomplete's <ul> element is focused. Defaults to true.
Displays the autocomplete list whenever the up arrow key or the down arrow key are pressed. Defaults to el.tagName === 'INPUT'.
A function that's used to decide what to display in each suggestion item. render will take the <li> element as the first argument, and the suggestion model as the second argument.
function defaultRenderer (li, suggestion) {
li.innerText = li.textContent = getText(suggestion);
}The example below would assign arbitrary HTML found in the suggestion model to each list item. Note that rendering doesn't necessarily have to be synchronous.
horsey(el, {
render: function (li, suggestion) {
li.innerHTML = suggestion.html;
}
});Where should the <ul> element containing the autocomplete options be placed? Generally an irrelevant option, but useful if you're dealing with a SPA, where you want to keep the element inside your view instead of the body, so that it gets cleaned up as the view goes away.
Defaults to document.body.
The form your el belongs to. If provided, the autocomplete list will be hidden whenever the form is submitted.
Once you've instantiated a horsey, you can do a few more things with it.
Just like when passing suggestions as an option, you can add individual suggestions by calling .add(suggestion). Returns the <li> element for this suggestion in the autocomplete list. There isn't an API method to remove the suggestion afterwards, so you'll have to grab onto the <li> reference if you want to remove it later on.
You can however, remove every single suggestion from the autocomplete, wiping the slate clean. Contrary to .destroy(), .clear() won't leave the horsey instance useless, and calling .add will turn it back online in no time.
The autocomplete list DOM <ul> element.
Exposes the suggestions that have been added so far to the autocomplete list. Includes suggestions that may not be shown due to filtering. This should be treated as a read-only list.
Shows the autocomplete list.
Hides the autocomplete list.
Updates the position of the autocomplete list relative to the position of the el. Only necessary when the el is moved.
Unbind horsey-related events from the el, remove the autocomplete list. It's like horsey was never here.
Detaches this horsey instance from el, removing events and whatnot, and then attaches the instance to target. Note that horsey.find will still only work with el. This method is mostly for internal purposes, but it's also useful if you're developing a text editor with multiple modes (particularly if it switches between a <textarea> and a content-editable <div>).
The default render method
The default getText method
The default getValue method
The default set method
The default filter method
Once you've instantiated a horsey, some propietary synthetic events will be emitted on the provided el.
| Name | Description |
|---|---|
horsey-selected |
Fired after a suggestion is selected from the autocomplete |
horsey-show |
Fired whenever the autocomplete list is displayed |
horsey-hide |
Fired whenever the autocomplete list is hidden |
horsey-filter |
Fired whenever the autocomplete list is about to be filtered. Useful to prime the filter method |
MIT