AJAX Suggestions – a new JavaScript library for you

Updated April 10th with a couple of features per comment suggestions

Ok, I’ve added a couple of features and settings based on the comments I’ve got. The additional settings are:

If a click on the document should hide the results list.
If the focus should be set to the input element, once an item has updated the input element’s value (by initially having the itemInsertValueIntoInputClassName CSS class).
If the results list should be hidden when the input element’s value is updated.

Another additional feature is that if you use the arrow keys to navigate the results list, arrow up from the first item as well as arrow down from the last, will set the focus back to the input element.

Updated April 11th

Changed the license to a Creative Commons Deed.

Updated April 13th

I got an e-mail with the suggestion to turn off the web browser autocompletion feature of the input element. I think it was a good idea, so I have now added it as a setting:

turnAutoCompleteOff : true

When most people need some kind of intellectual challenge, they do crosswords, sudokus, IQ tests, read up on philosophy or something similar. Me? I write some JavaScript. :-)

The thing is, though, that my small hobby scripts soon turn into something I think will be useful for other people, so I feel a strong urge to share it. Branded by having web developing as a living, after the initial rush and the proof of concept phase, more “sexy” matters come into my mind: scalability, performance, cross browser and cross platform support etc…

Anyway, once I’ve spent way too much time on that (and since I want to be a good father and husband, we’re talking late nights; basically, anytime when I seem to be the only person in the entire world awake), sooner or later I reach I time when I’m ready to share. Luckily, for my sanity, that time is now.


I think that for me, as well as many other web developers, the spark was lit when I saw Google Suggest for the first time. Since then, I’ve wanted to (re-)create that JavaScript since I think it’s a perfect example of good progressive enhancement; helping the end user, but it’s nothing vital that the whole web site depends on.

I was kind of hoping that a project would turn up where this was asked for, but it never came (at least not yet), so I had to give in and create the script in my free time. The good thing with that, however, is that I own the script and can bring it to any project I seem fit. I just hate leaving my “script babies” behind. :-)

The script and the concept

The result of my efforts is AJAX Suggestions!

The general idea is that, as soon as you type a couple of characters into an input element, a JavaScript makes an AJAX call to the server, which performs a search and returns the results/suggestions and displays them adjacent to the input element. The user can then click on, or navigate through the results with the keyboard, and choose the item they prefer.

I’ve also added some functionality to use this to do a look-up of the value in the input element, and when one of the results are chosen, it replaces the value in the input element with the value of the result. This can be useful, for instance, in a web-based e-mail application where you want to auto-complete recipients. No doubt, many will want to tweak this for their specific needs, and that’s just fine. My advice, however, is to override the methods in an external JavaScript file, in case I update the core AJAX Suggestions JavaScript file.


The script looks for elements that have the CSS class ajax-suggestion and then another CSS class, like url-the-actual-URL, where you should replace the-actual-URL with your desired URL for the AJAX call. The HTML code can look something like this:

<input type="text" class="ajax-suggestion url-ajax-demo.php">

Important to note is that AJAX Suggestions supports multiple elements in the same web page, who can also use different URLs for their AJAX calls. The same element is used for presenting the results, so it will only show you the results/suggestions for the latest search.

A library, in two versions

I’ve created two versions of this script. One that is completely stand-alone, and will automatically work as soon as it’s included into a web page (given that the element/-s contain the desired CSS classes, of course.)

The other one is written based on DOMAssistant, which means that is slightly smaller (and leaner, according to my taste).

License and copyright

AJAX Suggestions is released under a Creative Commons Deed license. Basically, it means that it’s free to use and improve, and that the JavaScript files keep their reference to its creator. Like this:

	AJAX Suggestions is developed by Robert Nyman, http://www.robertnyman.com, and it is released according to the
	Creative Commons Deed license (http://creativecommons.org/licenses/GPL/2.0/)
	For more information, please see http://www.robertnyman.com/ajax-suggestions

Where to go from here

Go to the AJAX Suggestions mini web site, where you can see a demo of AJAX Suggestions or read through the implementation page to find about all the available settings.

You can also directly download the stand-alone JavaScript file (10 kb) or the DOMAssistant-based JavaScript file (7 kb) and start playing! :-)

Note: remember to call the init() method of the ajaxSuggestions object, with the approach you find suitable, when using the DOMAssistant version.

A thanks to PPK

In the darkest hour of developing this, I was eating candy till I felt sick and drinking about one glass of water a minute out of pure exasperation. At that time, one certain person’s work with the ins and outs of the abort method really saved the day.

So, Peter-Paul Koch, thank you for your superb XMLHTTP notes: abort() and Mozilla bug article.


PS. You can also see it in use for the search input element of this very web site. :-) DS.

Posted in Developing,JavaScript |

Leave a Reply

Your email address will not be published. Required fields are marked *