A jQuery UI Combobox: Under the hood
read 45 commentsThe jQuery UI 1.8 release brings along the new autocomplete widget. An autocomplete adds a list of suggestions to an input field, displayed and filtered while the user is typing. This could be attached to a search field, suggesting either search terms or just matching results for faster navigation. But what if there is a fixed list of options, usually implemented as a standard HTML select element, where the ability to filter would help users find the right value way faster?
That's a "combobox." A combobox works like a select, but also has an input field to filter the options by typing. jQuery UI 1.8 actually provides a sample implementation of a combobox as a demo. In this article, we'll look under the hood of the combobox demo, to explore both the combobox widget and the autocomplete widget that it uses.
Let's starts with the initial markup:
- <label>Your preferred programming language: </label>
- <select>
- <option value="a">asp</option>
- <option value="c">c</option>
- <option value="cpp">c++</option>
- <option value="cf">coldfusion</option>
- <option value="g">groovy</option>
- <option value="h">haskell</option>
- <option value="j">java</option>
- <option value="js">javascript</option>
- <option value="p1">perl</option>
- <option value="p2">php</option>
- <option value="p3">python</option>
- <option value="r">ruby</option>
- <option value="s">scala</option>
- </select>
Nothing special there, just a label and a select element with a few options.
The code to apply the combobox widget to the select is quite simple, too:
- $("select").combobox();
Let's look at the code for this combobox widget. First, the full code, to give you an overview. We'll dig into the details step-by-step afterwards.
- $.widget( "ui.combobox", {
- _create: function() {
- var self = this;
- var input = $( "<input />" )
- .autocomplete({
- delay: 0,
- minLength: 0,
- source: function(request, response) {
- var matcher = new RegExp( $.ui.autocomplete.escapeRegex(request.term), "i" );
- return {
- new RegExp(
- "(?![^&;]+;)(?!<[^<>]*)(" +
- $.ui.autocomplete.escapeRegex(request.term) +
- ")(?![^<>]*>)(?![^&;]+;)", "gi"),
- "<strong>$1</strong>"),
- option: this
- };
- }) );
- },
- ui.item.option.selected = true;
- self._trigger( "selected", event, {
- item: ui.item.option
- });
- },
- if ( !ui.item ) {
- valid = false;
- if ( this.value.match( matcher ) ) {
- this.selected = valid = true;
- return false;
- }
- });
- if ( !valid ) {
- // remove invalid value, as it didn't match anything
- return false;
- }
- }
- }
- })
- return $( "<li></li>" )
- };
- $( "<button> </button>" )
- .button({
- icons: {
- primary: "ui-icon-triangle-1-s"
- },
- })
- // close if already visible
- if (input.autocomplete("widget").is(":visible")) {
- input.autocomplete("close");
- return;
- }
- // pass empty string as value to search for, displaying all results
- input.autocomplete("search", "");
- input.focus();
- });
- }
- });
Let's break this down, piece by piece:
- $.widget( "ui.combobox", {
- _create: function() {
- // all the code
- }
- });
This defines a new widget, in the ui namespace (don't use this for your own widgets, it's reserved for jQuery UI widgets) and adds the only method, _create. This is the constructor method for jQuery UI widgets, and will be called only once. In versions prior to 1.8 it was called _init. The _init method still exists, but it is called each time you call .combobox() (with or without options). Keep in mind that our widget implementation is not complete, as it lacks the destroy method. It's just a demo.
Coming up next is the creation of an input element and applying the autocomplete to it, with data provided by the select element.
- var self = this;
- var input = $("<input />")
- .autocomplete({
- delay: 0,
- minLength: 0
- source: function(request, response) {
- // implements retrieving and filtering data from the select
- },
- // implements first part of updating the select with the selection
- },
- // implements second part of updating the select with the selection
- },
- })
It starts with a few variable declarations: var self = this will be used inside callbacks below, where this will refer to something else. The var select references the select element on which the combobox gets applied. To replace the select with the text input, the select is hidden.
The selected and value variables are used to initialized the autocomplete with the current value of the select.
An input element is created from scratch, inserted after the select element into the DOM, and transformed into an autocomplete widget. All three autocomplete options are customized:
- delay specifies the amount of time to wait for displaying data between each key press, here set to zero as the data is local
- minLength is set to 0, too, so that a cursor-down or -up key press will display the autocomplete menu, even when nothing was entered.
- source provides the filtered data to display
Let's break down the source implementation:
- source: function(request, response) {
- var matcher = new RegExp( $.ui.autocomplete.escapeRegex(request.term), "i" );
- return {
- new RegExp(
- "(?![^&;]+;)(?!<[^<>]*)(" +
- $.ui.autocomplete.escapeRegex(request.term) +
- ")(?![^<>]*>)(?![^&;]+;)", "gi"),
- "<strong>$1</strong>"),
- option: this
- };
- }) );
- },
There is a bit of matching and mapping involved here: At first, a regular expression object is defined, based on the entered term, escaped with the help of the $.ui.autocomplte.escapeRegex utility method. This regex gets reused in the function below. The response argument, a callback, gets called, to provide the data to display. The argument passed is the result of the call to select.find("option").map(callback). That finds all option elements within our original select, then maps each option to a different object, implemented in another callback passed to the map method.
This callback will return undefined, thereby removing an item, when a search term is present and the text of the option doesn't match the entered value. Otherwise (no term, or it matches), it'll return an object with three properties:
- label: based on the text of the option, with the matched term highlighted with some regexing (another example of a write-only regular expression)
- value: the unmodified text of the option, to be inserted into the text input field
- option: the option element itself, to update the select (via the selected-property) or to pass on in custom events
The label and value properties are expected by the autocomplete widget, the option property has an arbitrary name, used here only by the combobox widget.
Before, I mentioned that the combobox widget customizes all three autocomplete options, but there were actually five options specified. The fourth and fifth properties, select and change, are event. This is the select implementation:
- ui.item.option.selected = true;
- self._trigger( "selected", event, {
- item: ui.item.option
- });
- },
The ui.item argument refers to the data we provided in the source option. Via the ui.item.option property we can update the underlying select to the selected item, as well as triggering a selected events for further customization of the combobox widget.
To cover the case where no selection is made, the change event is used:
- if ( !ui.item ) {
- valid = false;
- if ( this.value.match( matcher ) ) {
- this.selected = valid = true;
- return false;
- }
- });
- if ( !valid ) {
- // remove invalid value, as it didn't match anything
- return false;
- }
- }
- },
Here the entered value is used to try and match a selection. If the value doesn't match anything, it'll get removed, and the underlying select is set to an empty value, too.
The next block customizes the _renderItem method of the underlying autocomplete. This is necessary to output the highlighting on each row, as autocomplete by default will escape any html.
And finally, the last block creates the button that opens the full list of options:
- $( "<button> </button>" )
- .button({
- icons: {
- primary: "ui-icon-triangle-1-s"
- },
- })
- // close if already visible
- if (input.autocomplete("widget").is(":visible")) {
- input.autocomplete("close");
- return;
- }
- // pass empty string as value to search for, displaying all results
- input.autocomplete("search", "");
- input.focus();
- });
Another element is created on-the-fly. It gets tabIndex="-1" to take it out of the tab order, as it's mostly useful for mouse interactions. Keyboard interaction is already covered by the input element. It gets a title attribute to provide a tooltip and is inserted after the input element into the DOM. A call to .button() with some options together with a bit of class-mangling transforms the button into a Button widget that displays a down-arrow icon with rounded corners on the right (the input has rounded-corners on the left).
Finally a click event is bound to the button: If the autocomplete menu is already visible, it gets closed, otherwise the autocomplete's search method is called with an empty string as the argument, to search for all elements, independent of the current value within the input. As the input handles keyboard input, it gets focused. Having focus on the button would be useless or would require duplicate keyboard interaction that the input already supports.
And that's it! We can see that the autocomplete widget is flexible enough to allow all this with option customization, events, and calling a few methods. We don't have to "subclass" autocomplete (creating a new widget with the autocomplete as the parent prototype instead of $.widget). Instead, we can make the combobox mostly independent of any internal or private autocomplete methods. For the full experience and latest version, check out the combobox demo on the jQuery UI site.
Great info Jörn.
I still don't like that jQuery implements the classnames hardcoded in the code. I would have liked the classnames to be options. That way it would have been easier to for example have 2 of the same kind of widgets with different looks on a page. You would just send in different classnames.
I tried one time to extend a UI widget with my own code (I wanted to change the dialog to a version with nice looking shadows and such). My biggest problems was the classes (even if I had to update some HTML generating too), I got a nicve result in the end but had to overide most methods with some changes.
But anyhow nice post with good info =)
@Johan: Stuff like that should go to forum.jquery.com, but while we're here: Dialog has a dialogClass option that you can set to style individual dialogs. Tooltip will have that, too. Other widgets, like Accordion, don't need it as you can just set the extra class in your markup.
@Johan:
You can still style differently even with the same class names:
Now in your CSS, use the parent "style1" or "style2" class to change up the styles:
I'm only just recently getting really into javascript/AJAX/WebService type web development. Did I just catch that you can return a structure in javascript as one would return a structure in a C program? If so that could be extremely good information. I think its time I pick up a book on javascript basics because all of my javascript, so far, is based on picking up techniques from jQuery examples and what not, while trying to design an internal company website.
There is a question of combobox cause me lost a lot of brain cells.
It's about option list.
If there are a lot of options, menu of list is too long to display in the current screen viewport, I hope there is a overflow.
I did that work, but ...
When I want to click to scroll the slider, the focus of input is lost, the list of menu will be close...
I collapse. .
I might be missing something here, but don't <select> elements already have a form of auto-complete? That is, when the element has the focus and you start typing, the browser finds the first match to your typed string. What does the combobox autocomplete do extra? I'm not being rude, and it is a neat gadget, but I'm not sure it's worth adding yet more code to a page for a feature already present in browsers.
select elements only match to the beginning of the string you typed. The combobox also matches to internal strings,, and presents all matches together.
Select example: Type app, go the first item "apple," type it again, go to the second item "applications," type it again, go to the third item "applied science." If these were in alphabetical order, you could use the down arrow to scroll through them, but if they were not contiguous, you would not see all items that start with app all together.
Combobox example: Type app, pulldown presents apple, applications, applied science, bad apple, snapple, other apps....
The browser knows only the data you already entered before into that same field. Thats useful for a login form, where you have only a few values, or just one anyway.
This is for forms with data that the user knows about, but hasn't entered already. For example, a field that allows you to tag content - you'd offer existing tags, or let them enter their own.
Or for a registration form, where you could use this combobox widget for the country select.
The problem with the demo is the resizing. If you open up hte select box list and resize your browser window the input box moves to a new position but the opened list stays in a fixed position on screen. This makes it very odd looking.
Do you know how to make the opened list on resize to autoclose.
The $(window).resize(function() is probably the easiest to use but am not able to access the object methods to hide the list on the event.
Could you assist otherwise than this it is a great control.
Hi Jörn,
is possible uses the regex synthax with other source, like a array (ex: var elms = ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"]; )
The hilite in autocomplete make all the difference, but i can use only with combobox widget.
@Gabriel: Yeah, you can do that, as part of a custom source-option, similar to what happens here for the combobox.
Anyone have idea how make a regex for latin chars? Like São Paulo or Perú, When i typing Sao obviously not work cuz my city call São.
A mini list for chars with diacritic:
Gabriel, check out my accent folding extension at http://github.com/scottgonzalez/jquery-ui-extensions/blob/master/autocomplete/jquery.ui.autocomplete.accentFolding.js to get what you want. You can reduce the character map to just the characters you want or keep the full list.
The extension makes it so non-accented characters entered by the user will match accented characters in the results, but accented characters entered by the user must have an exact match in the results.
Thanks Scott, tonite i'll find way to use this... i really not the best programmer :S I think is really simple :)
Is possible uses Accent Folding extension with the combobox's hilite? I can only use one or another :\
I noticed the change event is not being fired when you select an item from the autocomplete dropdown with the mouse. It is only fired if you select by typing and then move focus to a different control. Any way to get the change event to fire from the mouse click?
I had the same problem as Alan. Adding the following code instad of the
changefunction helped me out:Combobox got various updates recently: http://github.com/jquery/jquery-ui/blob/master/demos/autocomplete/combobox.html
It'll be in the 1.8.3 release, once that is out, I'll update this article.
Thank you for your response. The select option works great. This control is --insert superlative here --
I also had the same problem, to use the 'ui.item.id' of the option in the select function, I had made a little chenge in the 'var input' source function:
var input =....
source: function( request, response ) {
var matcher = new RegExp( $.ui.autocomplete.escapeRegex(request.term), "i" );
response( select.children( "option" ).map(function() {
var text = $( this ).text();
var idOpt = $( this ).val();
if ( this.value && ( !request.term || matcher.test(text) ) )
return {
label: text.replace(
new RegExp(
"(?![^&;]+;)(?!<[^]*)(" +
$.ui.autocomplete.escapeRegex(request.term) +
")(?![^]*>)(?![^&;]+;)", "gi"
), "$1" ),
value: text,
id: idOpt,
option: this
};
}) );
},
Had the same problem, my solution:
Regards!!
XD
No offense to any developer, but I wanted to point out that without an ability to set the overall height of the open menu/list of items, this plugin has the potential to annoy a user.
A user that uses this combobox as they would a traditional select tag, would be pretty annoyed with having to use their browser scroll bars to find an item on a longer list than the list in this current demo. The select example used above is a very limited list.
To see what I mean: Try using combobox for a Country selection, and you will see what I mean.
Until this particular "screen real estate" issue is resolved, I as a jquery form developer would avoid using the combobox plugin as a select menu replacement.
@Carl: See http://view.jqueryui.com/master/demos/autocomplete/maxheight.html - type "a" to test.
Just updated the article to reflect the latest changes to the combobox demo in jQuery UI 1.8.4.
Having an issue if someone could be kind enough to help, I got the autocomplete combobox functioning but not properly. When I click the button to toggle the list, it causes a post and refreshes the page. Anything in particular I could be doing wrong to make this do this?
Keith, I had the same problem when building off this demo code. This is happening because the demo does not wrap the form elements on a
<form>tag, so the button press does nothing. Inside a form, it does. This is easily fixed by returning false from the button click behavior (you may also wish to stop the event from propogating):Hi Jörn Zaefferer,
Can you please explain how we set the event handlers for this? I have been trying out code from the jquery doc
I see unanswered questions on this in the jquery forum too, so it must either be way too obvious or way too obscure!
As an example:
What is wrong with this? Am I attaching the event handler to the wrong thing? Am I doing it too late or too early?
Thanks for any assistance!
Rob
:)
Hi All,In short, this is what is needed to create a combobox with an event handler for the "selected" event (should be "select", but combobox is only a prototype):
For more detail on this, see my blog post: Event Handling with the jQuery Autocomplete Combobox.
Rob
:)
The "match a selection" section that somewhat gives an example for doing a "mustmatch", doesn't translate over to using the autocomplete plug-in with multiple choices.
I understand the point of making a plug-in as simple as possible, keeping to its fundamentals, but this implementation seems a bit too bare bones. Even if people say it's really powerful... it doesn't seem to be an adequate replacement of Jörn's original one.
Can you tell me how to get the autocomplete menu widget to line up under the input field? (See this screenshot, or a working example of my problem here.) Maybe there is something wrong in the CSS positioning or the placement of the UL in the DOM. Or maybe the problem is that jquery.bgiframe.js (or another .js file) is from an earlier version of jQuery/jQueryUI. Thanks for any help!
So it doesn't have highlighting implemented at all? I love how that used to work in your old plug-in. I just wish it still worked with jQiery 1.4.2, but it doesn't.
Hi man!
This function have a bug.
On line 74 $( " " ) is very important setting button type = button, because all the input on the form when keypress try event submit.
Sorry my writing english.
There is one quite big issue with this plugin. When there is no option selected, everything is fine. But, when you have an option selected, it opens autocomplete list below input on load of the plugin. To fix this just add
input.autocomplete( "close");after line 16 of source function.
It took me some time to figure this out, hope it helps somebody.
When I try to load the widget like this:
$(function() {
$("select").combobox();
});
I get the following:
$("<input>").insertAfter(select).val(value).autocomplete({delay: 0, minLength: 0, source: function (request, response) {var matcher = new RegExp($.ui.autocomplete.escapeRegex(request.term), "i");response(select.children("option").map(function () {var text = $(this).text();if (this.value && (!request.term || matcher.test(text))) {return {label: text.replace(new RegExp(" (?![^&;]+;)(?!<[^<>]*)(" + $.ui.autocomplete.escapeRegex(request.term) + ")(?![^<>]*>)(?![^&;]+;)", "gi"), "<strong>$1</strong>"), value: text, option: this};}}));}, select: function (event, ui) {ui.item.option.selected = true;self._trigger("selected", event, {item: ui.item.option});}, change: function (event, ui) {if (!ui.item) {var matcher = new RegExp("^" + $.ui.autocomplete.escapeRegex($(this).val()) + "$", "i"), valid = false;select.children("option").each(function () {if ($(this).text().match(matcher)) {this.selected = valid = true;return false;}});if (!valid) {$(this).val("");select.val("");return false;}}}}).addClass is not a functionWhat could be wrong?
PS: (I set the widget code in a separated file, and loading after the dependencies);
Excellent combo box, but what if the user wants to input an option that isn't in the select list?
No Problem!
1) Insert below code after ~Line 8: ((( value = selected.val() ? selected.text() : ""; )))
myname=this.element[0].getAttribute('id');2) Insert below code after ~Line 11: ((( .val( value ) )))
.attr('name', myname)3) Remark Line ~50 ((( //$( this ).val( "" ); )))
Now just make sure your select box has an id and the newly created input box will now have the name of the id of the select box. The text in it will stay put so you can grab it on submission.
just my 2 cents
Hello,
Nice code... but i'm pulling my hairs from days with that f**** combobox.
All I need is a combobox who works like a select with the jquery ui css.
I explain : I use the autocomplete only in my input. I dont need a select with input with autocomplete like explain in your example. It must be readonly.
All I need is SELECT which has the same comportment than an HTML SELECT + jquery ui css.
Is it possible and how to do that ?
I dont see any documentation on how to stylize a stupid select with jquery ui.
Hope somebody can help me.
I made a fork of this that has a relevant improvement.
In the original version, when your select element has an "onchange" defined, the original version of the autocomplete combobox ignores it. I wrote my own fork that doesn't do that. It does however require two external functions: Left and Right, which I know isn't quite what we're after, but I've also included so you can mess with it:
Would you consider adding a trigger for the original select box's change event?
It's described here:
http://stackoverflow.com/questions/4760285/jquery-ui-combobox-onchange#answer-4761830
Having that added I was able to add this combobox to existing select elements with only minimal changes to my app--which is always nice. :)
Thanks,
Benjamin
Hi,
I have a requirement in which the client requires, the options returned should match the type words...rather than finding the charater in the whole string.
For example if the user types 'A' in the combo box. Only option with word A should be given as options. so what do I have to change
Hey I figured it out. I'm sure you have too, but for future visitors.
Under the source:
create a variable for EXAMPLE: var re = $.ui.autocomplete.escapeRegex(request.term);
then set the (var matcher = new RegExp( "^" + re, "i" );
Run it and it should work.
a have a problem to use my code inside the jquery ui - autocomplete combobox. please help.
i want to use the following code:
Hello. I love this widget but I have been stuggling for hours to try and figure out how to get it to autofill the input box, or do a SelectFirst or mouseenter on the first item. Any idea? I've seen bits and pieces of code referring to how to tweak the autosuggest to do autofill but nothing relating to the combobox application. Thanks!
Hi all,
is there a way to load data from an array instead of a list of options?
Could you please teach me how to do that?
Thank you!
Can anyone help with getting the regex to only display what is being typed if matched. Example: if you press c it will bring up everything that starts with c and not words with c in it? Any help would be great.
Can this combobox be added to the official jquery ui release?