bevacqua / horsey

:horse: Progressive and customizable autocomplete component

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 selected
• info.suggestions contains the list of suggestions at the time a suggestion was selected
• info.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 provided
• data.limit is the previously specified options.limit
• data.previousSelection is the last suggestion selected by the user
• data.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

Usage with woofmark

See banksy to integrate horsey into woofmark.

License

MIT

horsey's Issues

Filtering case sensitive

Is it intentional for the default filter to only match lowercase letters?
It works fine when users are typing because they typically don't use shift.
The problem is once an option is selected, deleting a character will no longer match.

Example

1. Initialize horsey with the following suggestions

horsey(document.querySelector('input'), {
  suggestions: ['0P.06.0QU', '0S.06.0QU', '0T.06.0QU']
});

1. Type q
2. You'll see the all three options
3. Select an option
4. The input is populated with the text
5. Delete the last character (in this case U)
6. No suggestions popup anymore

I spent about an hour trying to find if this was a bug in horsey failing to show the matches.
But it looks like the problem is just the case sensitivity 😞

I realize I can change the default filter function which is my solution.
However this might turn off new users since it not obvious why it doesn't work as expected.

Does select box update with typeahead?

Hi, I'm looking for a plain JS alternative to various jquery-based typeahead/autocomplete plugins like Selectize or Select2 or Chosen2. Horsey looks it fits the bill perfectly -- except that in the demo, the < select> dropdown does not update as the user types; essentially, it behaves the same as an HTML select. Is this piece of the demo broken, or does the dropdown not behave the same as contenteditable fields?

Scrollbox or keep item in view?

Can you extra pretty please add an option for a scrollbox for extra long lists of matches?
Using keyboard navigation you can currently navigate very long lists off screen which is not very good
An alternative (maybe better) option would be just keeping the currently selected item in view - without a scrollbar, somehow

Matches not refreshing after programmatically adding value and using .show()

jsFiddle

Steps to replicate:

Select "ap" from select element and click show

ap will be added as the value of the input and horsey will show correctly

Click hide

Select "ba" from select element and click show

ba will be added as the value of the input and horsey will show incorrectly
the suggestion for apple is still showing, and not banana

Live suggestion list

Hi! README.md contains:

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.

Does it mean the library doesn't suit use cases a suggestions list must be rebuilt on every input event (that is the cases with, say, million suggestions, and to form a limited list of most suitable items for every search term change is a server-side task)?

Keyboard arrow does not navigates over all suggestions matched on backend

Actually I search the same query into two field on database: name or email, but on getText I need to choose one field of suggestion JSON. There is some way to the navigation goes over all items based on one match or another?

In the same way I would like to highlight the both text:

John Doe
[e-mail]

See my question on: #32

One solutions was concat the strings I want to navigate:

getText: function(object) {
  return object.name + object.email;
}

So the keyboard can do the "indexOf" in some position. Bad, no?

Any options to choose more than on field inside the returned JSON?

How can I highligth the matched part of the text?

I want to type quan and it returns "bevacqua" on the text a choose, like, on key name or email.

May we, in some way, receive the q item here: https://github.com/bevacqua/horsey/blob/master/horsey.js#L150

So a can use replace(q, '<b></b>'), What do you think?

My hack:

render: function(li, suggestion) {
  var keys = ['email', 'name'];

  for (var i = 0; i < keys.length; i++) {
    var
      regex = new RegExp('(' + field.value + ')', 'i'),
      value = suggestion[keys[i]];

    suggestion[keys[i]] = value.replace(regex, '<b>$1</b>');
  }

  li.innerHTML = Templates.users.search(suggestion);
}

If you think all question with some kind of answer is good, I can try to implement a pull request.

sey-list incorrectly positioned when using appendTo

If you use the appendTo function to append the sey-list to something other than document.body, the left and right properties of the list are being set as if the list was still being appended directly to the body. This is easiest to see if you position an element that wraps the input field somewhere on the page, then set appendTo to point to that element. You'll notice top and left are being set to the position of that wrapper, but since the list is inside that wrapper, it ends up getting offset. Example:

http://cl.ly/fPjk
http://plnkr.co/HhRlVL5RNaZwDzwistkc

Make `defaultFilter` publicly available (somehow?)

Use case: use default filter method, with some additional conditions. For example, prevent suggesting previously used tags, it’d be nice to do something like:

filter: function (q, suggestion) {
  return !_this.insignia.tags().includes(suggestion) && this._super.apply(this, arguments);
}

Incorrect position of autocomplete box

Autocomplete box should be right under input, on blank page with default settings top position is incorrectly calculated.

Firefox 39, Chrome 43

http://i.imgur.com/iwndgNi.png

How to limit number of results?

If i have larger number of suggestions, how do i limit how much of suggestions are displayed in rendered box?

unable to use with an isomorphic js setup

If you try to require in horsey from a js file that is run from server (even if the creation of the horsey object does not happen on server) then your scripts are unable to run with the following error: ReferenceError: document is not defined . This also happens in horseys' dependencies. type checking document before using it seems to be the simplest solution. As a note I am trying to get horsey to work with a isomorphic react setup.

Character highlight broken by case-mismatches

The potential completions are case-insensitive, but a case mismatch between the input and the potential matches breaks things.

Example:
input: "he"
potential matches:
"hello" <- "he" is highlighted
"Heck!" <- nothing is highlighted, the initial case mismatch between the "h" and "H" breaks character highlighting.

Limiting results after X characters entered

Struggling with one thing, If I wanted to not show the autocomplete options until a user has entered X number of characters how would I do it, I suspect it has to do with filter but I'm having zero luck

Freezing up on large responses (w/ workaround)

There's an issue with the last few versions of Chrome that cause accessing the innerText of an element to take significantly longer than before (~70x in my testing). This causes problems performing highlighting on large datasets due to to this line:
https://github.com/bevacqua/horsey/blob/master/horsey.js#L392

In my case, processing a 3000 character response causes Chrome to freeze for approx. 6000ms.

This looks like it will be fixed in a future version of Chrome, so likely doesn't need a long term patch in horsey. However, if anyone is facing this issue and needs an immediate fix, a workaround is to remove innerText from the line above and rely solely on textContent.

The associated bug in Chromium is: https://bugs.chromium.org/p/chromium/issues/detail?id=935237

Vulnerability report with lodash dependency

During npm install, 2 severity vulnerabilities are introduced (1 moderate, 1 low) when installing horsey:

npm audit gives

                       === npm audit security report ===                        
                                                                                
                                                                                
                                 Manual Review                                  
             Some vulnerabilities require your attention to resolve             
                                                                                
          Visit https://go.npm.me/audit-guide for additional guidance           
                                                                                                                                           
  Moderate        Prototype Pollution                                                                                                              
  Package         lodash                                                                                                                            
  Patched in      >=4.17.11                                                                                                                    
  Dependency of   @goguardian/horsey                                                                                                                 
  Path            @goguardian/horsey > lodash                                                                                                       
  More info       https://npmjs.com/advisories/782                              
                                                                                
                                                                                
  Low             Prototype Pollution                                                                              
  Package         lodash                                                                                                                             
  Patched in      >=4.17.5                                                                                                                          
  Dependency of   @goguardian/horsey                                                                                                             
  Path            @goguardian/horsey > lodash                                                                                                  
  More info       https://npmjs.com/advisories/577 

Please update! @bevacqua is this library dead?

restart search

Is there a function to refresh the suggestions.
Maybe i want to implement an additional filter for suggenstions.
So i have to load it again.

Disabling highlighter is not possible

Currently, the highlighter option is not passed to the autocomplete function, so the option is effectively ignored.

Options for styling

Hi great library you have, here!

One thing I'm having trouble with is styling: there does not seem to be much flexibility. Perhaps I'm totally missing something, but it would be helpful to pass in some classes, at the least.

Diacritics

Not sure if this belongs here or in bevacqua/fuzzysearch, but is there a way to support including results that include diacritic/accent marks in them?

For example, if you have an item with text: São Tomé and Príncipe, searching for sao or tome should include that result (well, tome does work with this exact phrase, but just coincidentally because there is a normal e at the end).

Thank you.

customize source

How to customize bindata to soucre from ajax

What to use on place of "horsey-selected"

It was removed? I can't find it on code of some description on changelog.
How to know what category (suggestion) the user choosed?

Hiding list on blur in Firefox

Even when the autoHideOnBlur option is true, tabbing out of an input field that has an autocomplete list open in Firefox will not actually hide the list. Clicking outside the input, however, hides correctly.

Chrome and IE11 both work as expected.

provide a non-changing category container div at renderCategory()

In short, I am trying to implement a header and a footer in the menu:

-------------------------------
beautiful header
-------------------------------
[ item 1 ] <- highlight
item 2
item 3
-------------------------------
beautiful footer
-------------------------------

The renderCategory() seems to be a solution as it provides a div that I can modify. However, the item list is appended later and this makes it difficult to keep a footer child element at the end.

It would be good (to me) to append the ul element first beforehand. So when I receive the div from the renderCategory() function, the element layout is not changed by the library again and I can feel free to add child elements without worrying their order.

Suggestions don't hide on backspace till empty or clicking the X

When you backspace to remove all input, once input is gone, the suggestions box is still visible. It should auto hide

Capybara fill_in does not trigger the search

Since I updated to version 4.2.2, my integration test does not works. The method fill_in does not not trigger the search. So, there is some way to trigger the search manually? I would like something like that:

page.execute_script $('#user_id').val('bevacqua').trigger('search')

Just .val() does not trigger the search, neither the Capybara fill_in.

Thank you.

library breaks after production build with webpack

my build is fine without using UglifyJSPlugin. but with UglifyJSPlugin, I got the error in runtime:
TypeError: t.appendChild is not a function

so i have to import the minified version which is working fine.

sey-list incorrectly positioned when using textarea

When a multi-line text area is used and is displayed with the scroll bar, sey-list element goes too far down (probably because is calculating the raw number of lines ignoring textarea height).

Drop-down popup flickers when you type a character not available in data

e.g. by pressing "1" on the demo page in the first input control.
http://bevacqua.github.io/horsey/

Chrome, v40

How can I make highlighting case insensitive?

Letter highlighting seems to be case sensitive. I am just wondering how I might go about making it highlight letters regardless of uppercase and lowercase.

I took a look in the code it seems like the search gets around this by converting everything to lowercase, but ideally I would like to keep title case on my list items.

arrange results in pertinence order

I would like arrange my results in pertinence order with horsey.
Ex : input is "p", results are : "pomme" then "poire" then "épinard"

I tried to do it with "filter", but it seems return only boolean value so it classifies results only with the presence of the input.
Ex : input is "p", results are : "pomme" then "épinard" then "poire"

How do I use "horsey" in order to don't have boolean value and classify my results as I want ?

Thank you for your help !

Horsey + Insignia when tag is entered

Suggestions list persists (at old input position) when new tag is entered:

http://quick.as/6Qk8CXOZ

http://jsbin.com/kotirepiqi/1/edit?html,js,output

Allow different elements for list items

Would you accept a pull request to add an option for list item elements so that they could be something other than a li element?

https://github.com/bevacqua/horsey/blob/master/horsey.js#L129

I'm using Bootstrap and would like to use a list group of links, which requires the items to be a elements.

Horsey cannot work at 13 July 2016

Horse cannot run autocomplete, after download this project at 13 July 2016.

Not working in mobile Android browser

I tried horsey on several devices. It works in every Desktop browser I tested. Also on iOS browsers. But there seems to be a problem with the mobile Android browser (Chrome).

Typing in the box does not fire any events. No list is shown. I debugged it and there is no error message. You can test it at the sample page http://bevacqua.github.io/horsey/

Wrong suggestions ?

Why am getting 'Bananas' and 'Oranges' suggested when I enter the text "ornfs" ?
(the input text is just an experiment, I'm getting weird results on similar text while trying out the examples on the site)

EDIT: This only seems to happen when "key:value" is used. For "array of strings" suggestions are OK.

*I'm actually very impressed with this library. Looking forward to see how to fix this issue

Disallow input values if not in the provided suggestions

Is it possible to disallow input values if not in the provided suggestions? I see there is a .filter() method but I don't think I want to overwrite the default functionality, is that what I should use? Does anyone have any idea how to achieve this?

If my suggestions were like this:

suggestions: ['sports', 'drama', 'romantic comedy', 'science fiction', 'thriller']

and a user tried to add action as a field value, I would like to disallow that.

How to define more that two key:value pairs?

Hello,

I am just wondering what is the best way to utilise more than two key:value pairs?

Here is a jsFIddle test that seems to be working, with:

horsey(document.querySelector('input'), {
  source: [{ list: [
    { value: 'banana', text: 'Bananas from Amazon', description: '[ bananas are yellow ]'},
    { value: 'apple', text: 'Red apples from New Zealand', description: '[ apples are red ]' },
    { value: 'orange', text: 'Oranges from Moscow', description: '[ oranges are orange ]'},
    { value: 'lemon', text: 'Juicy lemons from Amalfitan Coast', description: '[ lemons are green ]'}
  ]}],
  getText: 'text',
  getValue: 'value',
  getValue: 'description',
  renderItem: function (li, suggestion) {
    var image = "<img class=\"autofruit\" src=\"" + fruits[ suggestion.value] + "\">";
    li.innerHTML = image + suggestion.text + " " + "<div class=\"second\">" + suggestion.description + "</div>";
  }
});

As you can see, getValue is used twice, which is probably not how it was intended to be used?

Matches don't occur as expected on description, however, if it is not called via getValue (eg searches for are will only return one suggestion).

How to disable search on focus

When the field is blank, on the firstfocus, it does a search withvalue` empty.
There is a way to avoid it? For me, it is useless search for nothing.

My hack:

suggestions: function(value, done) {
  if (value === '') {
    return done([]);
  }

  ...
}

Autocomplete suggestions above input

Is there a way to make the suggestions appear stacked above the input instead of below it? I looked through the js/css but didn't too far in my attempt, unfortunately. Thanks!

Performance for large datasets

I noticed that the implementation for the hide/show is just adding a class sey-hide.
This can get really slow for large datasets because changing the DOM is quite slow.
It also flashes the entire list upon typing the first letter before hiding items in the list that match.
I believe the performance can be improved dramatically if you do lazy rendering of the items such as select2 or slickgrid.

The downside would be a rigid height for each item in the list in order to calculate the position when scrolling. Maybe we can ignore the scrolling and instead switch to lazy rendering if a limit is imposed.
I can create a jsfiddle with an example of 1000+ items and then see if a lazy rendering solution performs better.

Are you interested or is this outside the scope of horsey?

Out-of-date browser support

Browser support includes every sane browser and IE7+.

I believe this statement in the README is incorrect. Even in the horsey.es5.js file, the ES6 Symbol is being used without a polyfill. Because of this, among other issues, horsey does not work on any version of IE.

Suggestions with type number are converted to undefined

horsey(document.getElementById('test'), {
    suggestions: ['aaa', 100, 200, 300]
});

will produce

http://i.imgur.com/QlqbUmr.png

How can I avoid the style left and top of sey-list

I trying to use appendTo to point to a fixed place into my template. This target is a sub wrapper, so I can use width: 100% to be equal the parents.

<div  class="search-box" style="width: 48%">
  <input type="text" style="width: 100%">
  <div  class="target">
    <ul style="left: 250px; top: 256px; width: 100%;"> <!-- I want just width: 100% here -->
    </ul>
  </div>
</div>

Any solution over !important?

No suggestions on IE11

On Internet Explorer 11 horsey fails to display suggestions. The developer console shows that on line 365 parent is undefined (an exception is thrown).

364:      for (let char of text) {
365:        parent.insertBefore(spanFor(char), el);
366:      }

I found out that document.createTreeWalker as used in getTextChildren is unsupported by IE (all versions according to MDN: https://developer.mozilla.org/de/docs/Web/API/Document/createTreeWalker). This seems to lead to parent being undefined.

IE11: Entries not selectable by clicking

On IE11 it is not possible to select entries in the dropdown be clicking: The dropdown disappears, but the textfield gets no value. I could reproduce this in my project and in every horsey demo.

Selecting them with the keyboard works perfectly.

PS: Looks like clickedSuggestion never get triggered crossvent.add(li, 'click', clickedSuggestion); replacing this by li.addEventListener('click', clickedSuggestion) does not change the deal. So I don't think that it is a crossvent issue.

Maybe related to this?: walmartlabs/thorax#299

Chinese input not work

When we input Chinese,it not work.May be the cause of the keyboard events(keydown or keyup)

How to use Events of horsey instance?

For example horsey-show.
I want to use some callback after user search.

how to put external source

I need to set external json file for the source parameter, it is not working,

horsey(document.querySelector('#serc'), {
source:index.php/Items/loadModeljson,
getText: 'text',
getValue: 'value'
}

Add support for browsers without Symbols

First off, thanks for the good work, this is an awesome library.

I'd like to ask if it is possible to add support for older browsers that do not support Symbol? When I try to run my app in such browser I get an error on this line that Symbol is undefined. I added a polyfill and yet again I'm getting an error:

Unhandled rejection TypeError: Property '[object Object]' of object Ivan is not a function

My data (suggestion) object is the following

{ value: "test", text: "Ivan", email: "test" } 

so obviously it's trying to get something off of the text key, which is a string, which made me think I was doing something wrong but then again on newer browsers everything is running fine. I also tried disabling the highlighter as I thought that would help but the error remains, as well as the highlighter..

Here is some code:

  activateHorsey(e: any) {
    e.disabled = true;
    e.placeholder = t("loading", true);
    console.log('a');
    return import("horsey").then(({ default: horsey }) => {
      console.log('b');
      horsey(e, {
        highlighter: false,
        source: (data: any, done: any) => {
          console.log('c');
          e.controlComponent.loading(true);
          console.log('d');
          web.request("/findUser", {
            data: {
              user: e.value
            }
          }).then((resp: any) => {
            console.log('e');
            done(null, [{
              list: resp.users.map((emailRecord: any) => ({
                value: emailRecord.email,
                text: emailRecord.user.name,
                email: FindUserControl.transformEmail(emailRecord.email)
              }))
            }]);
          }, function (error) {
            console.log("HORSEY ERROR", error);
          }).then(() => {
            console.log('f');
            e.controlComponent.loading(false);
          });
        },
        getText: "text",
        getValue: "value",
        set: function (text: string, data: any) {
          console.log('g');
          e.controlComponent.selectUser.call(e.controlComponent, data);
        },
        renderItem: function (li: HTMLLIElement, suggestion: any) {
          console.log('h', suggestion, li);
          li.appendChild(...);
          console.log("LILOG", li);
        }
      });

      e.disabled = false;
      e.placeholder = "";
    });
  }

And the output