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>