Skip to content

Latest commit

 

History

History
239 lines (185 loc) · 10 KB

README.md

File metadata and controls

239 lines (185 loc) · 10 KB
Raw

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>