jSuggest jQuery plug-in

Version 1.0 | Last revision Apr 11 - 2011

This plug-in will set up a UI that suggest results for your search queries as you type. You can add multiple selections as tokens and remove them on the fly. Built on top of the Autocomplete plugin by: Drew Wilson | www.drewwilson.com | code.drewwilson.com/entry/autosuggest-jquery-plugin


Simple version

This example takes as source for the suggestions an object. But the source can be also a url where you retrieve the suggestions from

  var dataSource = {
        items: [
          {value: "21", name: "Mick Jagger"},
          {value: "43", name: "Johnny Storm"},
          {value: "46", name: "Richard Hatch"},
          {value: "54", name: "Kelly Slater"},
          {value: "55", name: "Rudy Hamilton"},
          {value: "79", name: "Michael Jordan"}
        ]
      };

Associated code:

  // Assign the autosuggest plugin to the respective tag input.
      $('#TagsInputField').jSuggest({
        source: dataSource.items,
        selectedItemProp: "name", 
        seekVal: "name",
        selectionAdded: function(elem, data) {
          console.log(data.name);
        },
        selectionRemoved: function(elem, data) {
          console.log(data.name);
          elem.remove();
        }
        
     });

Type "m" to see some suggestions.


Prefill version

Associated code:

      $('#TagsInputField').jSuggest({
        source: dataSource.items,
        selectedItemProp: "name", 
        seekVal: "name",
        selectionAdded: function(elem, data) {
          console.log(data.name);
        },
        selectionRemoved: function(elem, data) {
          console.log(data.name);
          elem.remove();
        }
        
     });

Prefill source: (note that jSuggest only added the first 2 items becouse of the selectionLimit value has been taken into account.)

  var pref = {
        items: [
          {value: "21", name: "Mick Jagger"},
          {value: "43", name: "Johnny Storm"},
          {value: "46", name: "Richard Hatch"},
          {value: "54", name: "Kelly Slater"},
          {value: "79", name: "Michael Jordan"}
        ]
      };

Delete one item, type "hello" and press tab or comma to add "hello" as a new item.

Options

source: {}
Object or URL where jSuggest gets the suggestions from.


startText: 'Enter a Value'
Text to display when the jSuggest input field is empty.


emptyText: 'No Results Found'
ext to display when their are no search results.


preFill: {}
Object from which you automatically add items when the page is first loaded.


limitText: 'No More Values Are Allowed'
Text to display when the number of selections has reached it's limit.


newItem: false
If set to false, the user will not be able to add new items by any other way than by selecting from the suggestions list.


newText: 'Adding New Values Is Not Allowed'
Text to display when the user tries to enter a new item by typing.


loadingText: 'Loading...'
Text to display when the results are being retrieved.


selectedItemProp: 'value'
Value displayed on the added item.


selectProp: 'value'
Name of object property added to the hidden input.


seekVal: 'value'
Comma separated list of object property names.


queryParam: 'q'
The name of the param that will hold the search string value in the AJAX request.


queryLimit: false
Number for 'limit' param on ajax request.


extraParams: ''
This will be added onto the end of the AJAX request URL. Make sure you add an '&' before each param.


matchCase: false
Make the search case sensitive when set to true.


minChars: 1
Minimum number of characters that must be entered before the search begins.


keyDelay: 400
The delay after a keydown on the jSuggest input field and before search is started.


resultsHighlight: true
Option to choose whether or not to highlight the matched text in each result item.


selectionLimit: false
Limits the number of selections that are allowed.


showResultList: true
If set to false, the Results Dropdown List will never be shown at any time.


selectionClick: function(elem){}
Custom function that is run when a previously chosen item is clicked.


selectionAdded: function(elem, data){}
Custom function that is run when an item is added to the items holder.


selectionRemoved: function(elem, data){ elem.remove(); }
Custom function that is run when an item is removed from the items holder.


spotFirst: true
Option that spots the first suggestions on the results list if true.


formatList: false
Custom function that is run after all the data has been retrieved and before the results are put into the suggestion results list.


beforeRetrieve: function(string){ return string; }
Custom function that is run before the AJAX request is made, or the local objected is searched.


retrieveComplete: function(data){ return data; }


resultClick: function(data){}
Custom function that is run when a search result item is clicked.


resultsComplete: function(){}
Custom function that is run when the suggestion results dropdown list is made visible.


Get the code!

Fork us on GitHub!. The source code fully comented and the minified code is done with closure compiler with the "simple" optimization option.

This jSuggest jQuery plug-in is dual licensed under the MIT and GPL licenses:
http:// www.opensource.org/licenses/mit-license.php http:// www.gnu.org/licenses/gpl.html