---
title: "Customized jQuery UI Autocomplete Widget: List Items with description · Junaid Qadir"
description: "jQuery has made DOM parsing & manipulation easy for every developer out there. jQuery has provided a range of rich set of UI controls. My focus will be on how to customize the jQuery UI Autocomplete ("
url: "https://junaidqadir.com/blog/customized-jquery-ui-autocomplete-widget-item-list"
date: "2011-08-16"
tags: ["javascript", "jquery", "php"]
---

# Customized jQuery UI Autocomplete Widget: List Items with description

jQuery has made DOM parsing & manipulation easy for every developer out there.

jQuery has provided a range of rich set of UI controls. My focus will be on how to customize the jQuery UI Autocomplete (version 1.8.15) widget item list according to our needs. Our requirement for the customized item list were:

Each Drop-down item should have a description beneath it.  
Item should appear in bold face & it’s description should be small.

By default, the jQuery UI Autocomplete appears like this:

Figure1: Default appearance of the Autocomplete widget.

but we want it to look like this:

Figure2: Customized Autocomplete widget with item list visible.

The demo accompanied with the jQuery UI [download](http://jqueryui.com/download) uses the code below to display results in **Figure1**:

$(function () {

var availableTags = \[

“ActionScript”,

“AppleScript”,

“Asp”,

“BASIC”,

“C”,

“C++”,

“Clojure”,

“COBOL”,

“ColdFusion”,

“Erlang”,

“Fortran”,

“Groovy”,

“Haskell”,

“Java”,

“JavaScript”,

“Lisp”,

“Perl”,

“PHP”,

“Python”,

“Ruby”,

“Scala”,

“Scheme”

\];

$(“#tags”).autocomplete({

source: availableTags

});

});

[view raw](https://gist.github.com/JunaidQadirB/c612b3f9325e66ea51200de83d3d2885/raw/b442bdc7d5368ec210c5abfe1becdcd3c0b03c2e/available-tags.js)  
[  
available-tags.js  
](https://gist.github.com/JunaidQadirB/c612b3f9325e66ea51200de83d3d2885#file-available-tags-js)  
hosted with ❤ by [GitHub](https://github.com/)

The id “tags” is attached to the input tag.

This code is pretty simple & self explanatory. Isn’t it?

Going back to our requirements, we have to display a description for each item.

For this, there may be many more better ways to do it but I opted to add a separator to each item and then _split()_’ed the item text from the separator if it had parentheses. Then, I wrapped each of two items in tags (you can use div if you like) so that I can change their style accordingly.

The separator can be any punctuation mark, say an hyphen (-), a pipe (|) etc. I went with the small opening parenthesis ‘(’ because the list I received has already it’s description part inside these parentheses.

## Customizing the Autocomplete Plug-in (Not Really):

Now, this is what I call the meat of this post.

**Note:** _Instead of modifying the original source, its always a better idea to copy that part from the original source to a new place and do required changes._

jQuery has built into it, a low-level function called _.data()_ which stores key-value-pair (KVP) data and associates it with a given element. The element and a key is passed to the _.data()_ to retrieve the value stored with that key within the given element. check out official [jQuery API documentation](http://api.jquery.com/jQuery.data/ "jQuery API documentation") about _.data() for a detailed explanation with code examples_.

When we type in to the Autocomplete widget’s textbox, a dozen of private & public functions/events are called to search, filter, _render_ and finally, display the list on the screen. Of all those functions, _\_renderItem()_ function and the _select()_ event are of interest because these are the places where we can override stuff.

You should already know that the \_ (underscore) prefix to a function tells that the function is private.

The original code looks like this:

[https://gist.github.com/JeyKeu/c612b3f9325e66ea51200de83d3d2885#file-jquery-ui-autocomplete-js](https://gist.github.com/JeyKeu/c612b3f9325e66ea51200de83d3d2885#file-jquery-ui-autocomplete-js)

`/* * jquery.ui.autocomplete.js * Line Number: 449 * */ _renderItem: function( ul, item) { return $( "<li></li>" ) .data( "item.autocomplete", item ) .append( $( "<a></a>" ).text( item.label ) ) .appendTo( ul ); }`

Check out Git Hub [source.](https://github.com/jquery/jquery-ui/blob/master/ui/jquery.ui.autocomplete.js#L449 "_renderItem at line number 449 on Git Hub")

Lets now customize or should I better say override the _\_renderItem()_ function:

\_renderItem = function(ul, item) {  
itemTitleDesc = split(item.value);  
var desc = “”;  
if (is\_array(itemTitleDesc)) {  
itemTitle = itemTitleDesc\[0\];  
if (itemTitleDesc.length > 1) {  
itemDesc = itemTitleDesc\[1\];  
itemDesc = itemDesc.replace(“)”, “”);  
desc = ‘  
’ + itemDesc + ‘’;  
}  
var itemContent = ‘**’ + itemTitle  
\+ ‘**’ + desc;  
return $(“

”).data(“item.autocomplete”, item).append(  
$(“”).html(itemContent)).appendTo(ul);  
} else {  
return $(“

”).data(“item.autocomplete”, item).append(  
$(“”).html(item.label)).appendTo(ul);  
}  
};

Let me now explain the code to understand better what is happening. I won’t be getting into deeper details though.

For our case, whenever the function receives an _item_, it has a _value_ of the form \[_tile_\] **(** \[d\_escription\_\] **)**, therefore, we always want to break that into two parts from the first opening round bracket (parenthesis) and then get rid of the closing bracket\*\*.\*\* Obviously, the first & the second part of the string will serve as the **title** and **description**, for the items in the list. Then wrap each of them into their own span or div. All of this stuff is stored in the _itemContent_ _variable._

So, that was for the items in the list, now if we type in the text box, we get the nice list of items with their descriptions but we are not done yet because as soon as we select an item from the list, the text box would just be filled with the whole string including the parentheses because we haven’t told jQuery to what to do when a user ’select’s an item.

We get the “raw” text because we haven’t done anything on the select event.

`select : function(event, ui) { itemTitleDesc = split(ui.item.value); if (is_array(itemTitleDesc)) { itemTitle = itemTitleDesc[0]; if (itemTitleDesc.length > 1) { itemDesc = itemTitleDesc[1]; itemDesc = itemDesc.replace(")", ""); } ui.item.value = itemTitle; } }`

Now, lets just put everything together:

$(“#tags”).autocomplete({  
source : availableTags,  
select : function(event, ui) {  
itemTitleDesc = split(ui.item.value);  
if (is\_array(itemTitleDesc)) {  
itemTitle = itemTitleDesc\[0\];  
if (itemTitleDesc.length > 1) {  
itemDesc = itemTitleDesc\[1\];  
itemDesc = itemDesc.replace(“)”, “”);  
}  
ui.item.value = itemTitle;  
}  
}  
}).data(“autocomplete”).\_renderItem = function(ul, item) {  
itemTitleDesc = split(item.value);  
var desc = “”;  
if (is\_array(itemTitleDesc)) {  
itemTitle = itemTitleDesc\[0\];  
if (itemTitleDesc.length > 1) {  
itemDesc = itemTitleDesc\[1\];  
itemDesc = itemDesc.replace(“)”, “”);  
desc = ‘  
’ + itemDesc +  
‘’;  
}  
var itemContent = ‘**’ + itemTitle +  
‘**’ + desc;  
return $(“

”)  
.data(“item.autocomplete”, item)  
.append($(“”).html(itemContent))  
.appendTo(ul);  
} else {  
return $(“

”)  
.data(“item.autocomplete”, item)  
.append($(“”).html(item.label))  
.appendTo(ul);  
}  
};  
});

Here are the two utility functions which I used to check for array and the other that splits the string.

Google gave me this. How lazy I am 😉

function is\_array(input) {  
$ret = typeof (input) == ‘object’ && (input instanceof Array);  
return $ret;  
}

function split(val) {  
return val.split(“(”);  
};

I hope this article serves it’s purpose.

Please do give your feedback.

Regads.

[JavaScript](https://junaidqadir.com/blog/tag/javascript)[jQuery](https://junaidqadir.com/blog/tag/jquery)[PHP](https://junaidqadir.com/blog/tag/php)

---

Markdown version of https://junaidqadir.com/blog/customized-jquery-ui-autocomplete-widget-item-list
Site guide for agents: https://junaidqadir.com/llms.txt
Full index: https://junaidqadir.com/sitemap-index.xml