jQuery Autocompleter Plugin

Demo

Here: Example with Crayola colors.

Usage

Installation

npm:

npm install --save jquery-autocompleter

Yarn:

yarn add jquery-autocompleter

Add plugin to your project

include jQuery:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>

include plugin's code:

<!-- Styles -->
<link rel="stylesheet" href="css/jquery.autocompleter.css" />

<!-- Scripts -->
<script src="js/jquery.autocompleter.min.js"></script>

call the plugin:

$("input").autocompleter({
  /* options */
});

Examples

remote url

$(function () {
  $("input").autocompleter({ source: "path/to/get_data_request" });
});

plain

var data = [
  { value: 1, label: "one" },
  { value: 2, label: "two" },
  { value: 3, label: "three" },
];

$(function () {
  $("input").autocompleter({ source: data });
});

Options

Autocompleter has the following options:

Name	Type	Description	Deafult
source	str, obj	URL to the server or a local object	null
asLocal	bool	Parse remote response as local source	false
empty	bool	Launch if value is empty	true
limit	int	Number of results to be displayed	10
minLength	int	Minimum length for autocompleter	0
delay	int	Few milliseconds to defer the request	0
customClass	array	Array with custom classes for autocompleter element	[]
cache	bool	Save xhr data to localStorage to avoid the repetition of requests	true
cacheExpires	int	localStorage data lifetime in sec (0 to disable cache expire)	86400
focusOpen	bool	Launch autocompleter when input gets focus	true
enterSelect	bool	Allows to select using enter key	true
hint	bool	Add hint to input with first matched label, correct styles should be installed	false
selectFirst	bool	If set to `true`, first element in autocomplete list will be selected automatically, ignore if changeWhenSelect is on	false
changeWhenSelect	bool	Allows to change input value using arrow keys navigation in autocomplete list	true
highlightMatches	bool	This option defines `<strong>` tag wrap for matches in autocomplete results	false
ignoredKeyCode	array	Array with ignorable keycodes, by default: `9, 13, 17, 19, 20, 27, 33, 34, 35, 36, 37, 39, 44, 92, 113, 114, 115, 118, 119, 120, 122, 123, 144, 145`	[]
customLabel	str	The name of object's property which will be used as a label	false
customValue	str	The name of object's property which will be used as a value	false
onBeforeSend	function	This function is triggered before an ajax request	$.noop
onBeforeShow	function	This function is triggered when the list is ready to be shown	$.noop
onEmpty	function	If data list if empty, trigger this function	$.noop
onItem	function	This function is triggered when each item is being prepared to be shown	$.noop
onListOpen	function	This function is triggered when the list is shown	$.noop
onListClose	function	This function is triggered when the list is hidden	$.noop
onBeforeLaunch	function	The event was triggered before the new request (including local cache)	$.noop
template	str	Custom template for list items. For example: `<span>{{ label }} is {{ customPropertyFromSource }}</span>`. Template appends to `.autocompleter-item`.	false
offset	str	Source response offset, for example: `"response.items.posts"`. @deprecated use `format` instead	false
format	function	Format response payload to return source data	null
combine	function	Returns an object which extends ajax data. Useful if you want to pass some additional server options	$.noop
callback	function	Select value callback function. Arguments: `value`, `index`, `object`	$.noop

Methods

Change option after plugin is defined

$("#input").autocompleter("option", data);

For example:

$("#input").autocompleter("option", {
  limit: 5,
  template:
    '<img src="{{ image }}" alt="Image for autocompleter list item" /> {{ label }}',
});

Open list

$("#input").autocompleter("open");

Close list

$("#input").autocompleter("close");

Destroy plugin

$("#input").autocompleter("destroy");

Clear all cache

$.autocompleter("clearCache");

Set defaults

$.autocompleter("defaults", {
  customClass: "myClassForAutocompleter",
});

One more example

Autocompleter for the first name input with caching, match highlighting and 5 results limit. Remote response depends on a gender:

Form markup

<fieldset>
  <label>Male</label>
  <input type="radio" name="gender" value="male" checked="checked" />

  <label>Female</label>
  <input type="radio" name="gender" value="female" />

  <label>Other</label>
  <input type="radio" name="gender" value="other" />

  <label>First Name</label>
  <input type="text" name="firstname" id="firstname" />
</fieldset>

Code

$(function () {
  $("#firstname").autocompleter({
    source: "https://EXAMPLE_API_ENDPOINT.com/api/search/name",
    limit: 5,
    cache: true,
    combine: function (params) {
      var gender = $("input:radio[name=gender]:checked").val();

      // passing params to match endpoint
      return {
        q: params.query,
        count: params.limit,
        gender: gender,
      };
    },
    format: function (data) {
      // map response data to match autocompleter
      return data.entries.map(function (item) {
        return {
          label: item.name,
          value: item.slug,
        };
      });
    },
    callback: function (value, index, object) {
      console.log(
        "Value " + value + " are selected (with index " + index + ")."
      );
      console.log(object);
    },
  });
});

Markup

div (node) -> ul (list) -> li (item).

<div class="autocompleter" id="autocompleter-1">
  <ul class="autocompleter-list">
    <li class="autocompleter-item">First</li>
    <!-- ... -->
    <li class="autocompleter-item">Last</li>
  </ul>
</div>