Horsey
Progressive and customizable autocomplete component
Browser support includes every sane browser and IE7+.
Demo!
You can see a live demo here.
Inspiration
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.
Features
- Small and focused
- Natural keyboard navigation
- Progressively enhanced
- Extensive browser support
- Fuzzy searching
- Supports
<input>
and<textarea>
elements
Install
You can get it on npm.
npm install horsey --save
Or bower, too.
bower install horsey --save
Options
Entry 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
.
predictNextSearch(info)
Runs when a tag is inserted. The returned string is used to pre-fill the text input. Useful to avoid repetitive user input. The suggestion list can be used to choose a prefix based on the previous list of suggestions.
info.input
contains the user input at the time a suggestion was selectedinfo.suggestions
contains the list of suggestions at the time a suggestion was selectedinfo.selection
contains the suggestion selected by the user
cache
Can be an object that will be used to store queries and suggestions. You can provide a cache.duration
as well, which defaults to one day and is specified in seconds. The cache.duration
is used to figure out whether cache entries are fresh or stale. You can disable autocomplete caching by setting cache
to false
.
limit
Can be a number that determines the maximum amount of suggestions shown in the autocomplete list.
filter(query, suggestion)
By default suggestions are filtered using the fuzzysearch
algorithm. You can change that and use your own filter
algorithm instead.
source
A source(data, done)
should be set to a function. The done(err, items)
function should provide the items
for the provided data.input
.
data.input
is a query for which suggestions should be provideddata.limit
is the previously specifiedoptions.limit
data.previousSelection
is the last suggestion selected by the userdata.previousSuggestions
is the last list of suggestions provided to the user
The expected schema for the items
object result is outlined below.
[category1, category2, category3]
Each category is expected to follow the next schema. The id
is optional, all category objects without an id
will be treated as if their id
was 'default'
. Note that categories under the same id
will be merged together when displaying the autocomplete suggestions.
{ id: 'here is some category', list: [item1, item2, item3] }
blankSearch
When this option is set to true
, the source(data, done)
function will be called even when the input
string is empty.
noMatches
Defaults to null
. Set to a string if you want to display an informational message when no suggestions match the provided input
string. Note that this message won't be displayed when input
is empty even if blankSearch
is turned on.
debounce
The minimum amount of milliseconds that should ellapse between two different calls to source
. Useful to allow users to type text without firing dozens of queries. Defaults to 300
.
highlighter
If set to false
, autocomplete suggestions won't be highlighted based on user input.
highlightCompleteWords
If set to false
, autocomplete suggestions won't be highlighted as whole words first. The highlighter will be faster but the UX won't be as close to user expectations.
renderItem
By default, items are rendered using the text for a suggestion
. You can customize this behavior by setting autocomplete.renderItem
to a function that receives li, suggestion
parameters. The li
is a DOM element and the suggestion
is its data object.
renderCategory
By default, categories are rendered using just their data.title
. You can customize this behavior by setting autocomplete.renderCategory
to a function that receives div, data
parameters. The div
is a DOM element and the data
is the full category data object, including the list
of suggestions. After you customize the div
, the list of suggestions for the category will be appended to div
.
API
Once you've instantiated a horsey
, you can do a few more things with it.
.clear()
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.
.source
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.
.show()
Shows the autocomplete list.
.hide()
Hides the autocomplete list.
.toggle()
Shows or hides the autocomplete list.
.refreshPosition()
Updates the position of the autocomplete list relative to the position of the el
. Only necessary when the el
is moved.
.destroy()
Unbind horsey-related events from the el
, remove the autocomplete list. It's like horsey
was never here.
.retarget(target)
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>
).
.anchor
The anchor value that was originally passed into horse
as options.anchor
.
.defaultRenderer
The default render
method
.defaultGetText
The default getText
method
.defaultGetValue
The default getValue
method
.defaultSetter
The default set
method
.defaultFilter
The default filter
method
.appendText
Method called whenever we have an anchor
and we need to append a suggestion to an input field. Defaults to defaultAppendText
.
.appendHTML
Method called whenever we have an anchor
and we need to append a suggestion for a contentEditable
element. Unsupported by default. Provided by banksy.
.defaultAppendText
Default appendText
implementation
.filterAnchoredText
Method called whenever we have an anchor
and we need to filter a suggestion for an input field.
.filterAnchoredHTML
Method called whenever we have an anchor
and we need to filter a suggestion for a contentEditable
element. Unsupported by default. Provided by banksy.
Events
Once you've instantiated a horsey
, some propietary synthetic events will be emitted on the provided el
.
Name | Description |
---|---|
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 |
woofmark
Usage withSee banksy to integrate horsey
into woofmark.
License
MIT