/jquery-autocompleter

Easy customisable and with localStorage cache support.

Primary LanguageJavaScriptMIT LicenseMIT

jQuery Autocompleter

Demo

Here: Example with Crayola colors.

Usage

Installation

Bower:

bower install Autocompleter

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
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
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 false
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

<label for="gender_male">Male</label>
<input type="radio" name="gender" value="male" id="gender_male" checked="checked">

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

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

Code

$(function() {
  $('#firstname').autocompleter({
    limit: 5,
    cache: true,
    combine: function(params) {
      var gender = $('input:radio[name=gender]:checked').val();

      return {
        q: params.query,
        count: params.limit,
        gender: gender
      };
    },
    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>