autocomplete

Autocomplete component

Installation

$ component install matthewmueller/autocomplete

Example

<input type="search" id="search" name="keyword">

autocomplete(document.getElementById('search'), '/search/:keyword')
  .parse('result')
  .label('title')
  .value('url')
  .when(function(v) { return v.length > 2 })
  .format(function(label, q) {
    var r = new RegExp('(?:' + q + ')', 'i');
    return label.replace(r, '<span class="highlight">$&</span>');
  })
  .on('select', function(url) {
    img.src = url;
  })

Events

• enabled autocomplete is now listening for user input
• disabled autocomplete is no longer listening for user input
• response (res) response object after running through autocomplete#parse
• error (err) emitted when the server responds with an error
• select (value) emitted when you select an item from the autocomplete menu

API

autocomplete(el, url, [opts])

Initialize a new Autocomplete instance. Pass in an input el, a url endpoint and some options.

url may take a single express-style parameter to be used as the query key. You can specify the query key by either setting the input[name] or calling autocomplete#key(...). If no query key is present, autocomplete will pass the query through as a querystring.

Available options include:

• throttle : Defaults to 200. Throttles the user input to reduce the number of AJAX calls.

• headers : Defaults to superagent's default headers. Allows setting custom request headers for AJAX calls.

autocomplete(el, "https://api.github.com/legacy/repos/search/:keyword")

#enable()

Enables the autocomplete.

autocomplete.enable()

#disable()

Disables the autocomplete.

autocomplete.disable()

#key(key)

The query key used as either part of the query string or express-style parameter. May also be set by adding a name attribute to the input el.

autocomplete.key('q') // http://google.com/?q=...

#when(regexp|function)

Filter out queries that do not pass the regexp or function. You can use this to specify various formats for the queries or provide a minimum number of characters.

// only search when we have an input length of more than 2
autocomplete.when(function (v) { return v.length > 2 })

#display(display)

Displays the menu. display defaults to true. You may set this false if you just want to use the search feature without the autocomplete menu.

autocomplete.display(false)

#parse(key)

Parses the result object called immediately after a successful response from the server. This is useful for preparing the data. Many times you don't recieve a direct result set, but instead an object containing the results, maybe something like { result : [...] }. key may be a string or a function and supports to-function notation.

autocomplete.parse('result')

or as a function

autocomplete.parse(function(res) {
  return res.result;
})

#label(key)

Determines which key from the result object should be used to map label names in the menu. key may be a string or a function. label uses to-function, so you may use dot notation to traverse the result object.

autocomplete.label('name.first')

or as a function

autocomplete.label(function(item) {
  return item.name.first;
})

#value(key)

Determines which key from the result object should be used to map to values in the menu. This data is what will be passed when the user selects an item on the menu. key may be a string or a function and supports to-function notation.

autocomplete.value('url')

or as a function

autocomplete.value(function(item) {
  return item.url;
})

#format(formatter)

Format the menu items. Pass a formatter(label, query) function in to modify menu items. Useful for styling the result, such as providing query highlighting.

Here's how to highlight the query within the menu

autocomplete.format(function(label, query) {
  var r = new RegExp('(?:' + q + ')', 'i');
  return label.replace(r, '<span class="highlight">$&</span>');
})

#search(fn)

Call search to manually execute a search. This is usually called by default as you type, but may be useful for one-off searches or if you disabled autocomplete. Optionally you may pass an fn function to handle the results or listen for the response event. Please note that res is run through autocomplete#parse beforehand.

autocomplete.search(function(err, res) {
  if(err) throw err;
  console.log(res);
})

#menu

Access to the raw menu component. Useful for listening to specific menu events.

#position(fn)

Used to manually modify the position of the menu. May be useful for providing additional menu styling like carets and stuff. fn must return a position object with x and y keys.

Here's the default fn

autocomplete.position(function(el) {
  var coords = getOffset(el),
      x = coords.left,
      y = coords.top + el.offsetHeight;

  return { x : x, y : y };
})

Test

$ make test
$ open http://localhost:7000

License

MIT