How To Use the jQuery UI Autocomplete Widget

jqueryDropdowns are a lot less irksome to use when the screen gives you a little help by “suggesting” what you’re after with a list of possible entries.  The jQuery UI autocomplete widget makes it all pretty easy to set up.  The widget works against a pre-populated list and as the user types, the widget filters against the list to get to the right entry. Any field that can receive input can be associated with an autocomplete widget.  When such a field is given focus or the user types a value in the field, the autocomplete widget starts to search its predefined list of entries for a match.  As more characters are entered, the list of candidates is further filtered until the proper one is displayed.  jQuery UI widgets are objects that get connected to DOM elements (like an input form).  The widget object can store the state of the widget, and can communicate with other objects on the page – all with the goal of simplifying the coding necessary to use a process like autocomplete.

As you know, JQuery UI is a set of user interface widgets, themes, and interactions that is built on top of the jQuery JavaScript library – just like jQuery itself is built on JavaScript.   Let’s start with a few simple examples of autocomplete and then we’ll explore the process in more detail.   (New to jQuery UI?  Learn the Basics).   Widgets are objects that are connected to elements on the page that provide services such as states, theming, and communication with other widgets or JavaScript objects.  (New to widgets?  Learn more here).

The position option (bolded below) controls where the suggestions menu will appear in relation to the input element with which it is associated.

$( “#mySelector” ).autocomplete({position: {my : “right top”, at: “right bottom } } );

The value in the “my:” parameter refers to the element being positioned – in this case the suggestions menu. The “at:” parameter refers to the position of the target element to align the “my” element against.  It’s like saying match the “x” tab on the suggestions menu to the “y” tab of the input field.

The minlength option is straightforward and simply specifies the minimum number of characters that need to be entered before a search for suggestions is performed.

$( “.#mySelector” ).autocomplete( {minlength: 2 });

If the search list is relatively short, then 0 is a sensible value.  If the search list has thousands of items, you probably don’t want to start a search until more characters are entered – to prevent frequent searches through a long list.

The delay option controls the time in milliseconds between a keystroke and the start of a search.

$( “.#mySelector” ).autocomplete( {delay: 250 });

As is true for the minlength option, a small or zero value for delay could cause inefficiencies when the search list is very large.

The autofocus option is Boolean and it controls whether or not the first item in the list will be given focus when the list is displayed.  If autofocus is set to true, the first item is given focus.  If autofocus is set to false, the first item will not be given the focus.  The default value is false.

$( “.mySelector” ).autocomplete( {autofocus: true });

The appendTo option determines what DOM element the menu is attached to.   If the value is null and no other candidate is found (based on class inclusion), the menu is appended to the body element.

$( “.mySelector” ).autocomplete( {appendTo: “#myElement” });

Let’s look at a simple working example of autocomplete.  If you look carefully at the code below, you’ll see that it really is one major script that takes care of the selection list and setting up the autocomplete process on the input field.   The example lets autocomplete use default values, except obviously for pointing it at the source variable for the selection list.  The DIV holding the input field is given a class value that autocomplete looks for and the input field is given the id value used as the selector in the autocomplete call.


Try this example out in your browser so you get the feel of the process.  Just remember to modify the src= values and the links in the scripts up top to point at the libs you need.

The autocomplete widget is built with the jQuery UI Widget Factory.  As you get deeper in to jQuery and jQuery UI you may get to the point where you want to build your own widget, which is very doable with the Widget Factory documentation as a guide.  The widget factory gives you a structure and a common API that lets you build state-full widgets without re-producing all the structural code each time.  It also makes your widget easier to consume by others because it will have a common API so there’s nothing new for the user to figure out.

So, in conclusion, we just scratched the surface here on widgets.   To learn more look here at Udemy.