Home

Configuration options

• activeItemClass: the css class to apply to the currently highlighted <li> list item in the autocomplete dropdown.
• dataMethod: A callback method you supply that Awesomecomplete will call when it needs to get data. The method will be called with the following params:
  

  var dataMethod = function(term, $awesomecomplete, onData)
  {
    // term is the search term the user entered.
    // $awesomecomplete is the textfield object that you made an
    //                  awesomecomplete and is trying to get data.
    // once you have your data, call onData with an array of your data
  };

• attachTo: A jQuery object (or a DOM element; the plugin rewraps just to be safe) that you would like to “attach” the autocomplete suggestions list to instead of the textbox itself, which is the default. This is useful if, say, you wrap your textbox in <div>s for the sake of rounded corners and would like the autocomplete suggestions to be on the outside of that instead of inside.
• dontMatch: An array of strings representing the names of the data fields that you don’t want the plugin to search for data. For instance, if you don’t want the object.id or object.image_url to be searched, you’d give [ 'id', 'image_url' ].
• highlightMatches: If this is set to true, as the plugin is searching your data it will create a copy of it with the found terms wrapped in <span> tags. This copy of the data is then what is eventually given to you in your renderFunction.
• highlightClass: The class to assign to the spans that wrap the found term matches, as described in highlightMatches above.
• ignoreCase: Whether to do a case-insensitive search while matching terms.
• nameField: This field will be searched like any other, but it is particular in that it cannot be chosen as the best-match field. The idea is that if you have, for instance, a person, you’ll always want to show the person’s name, so choosing that as the best-match field isn’t a particularly useful thing to do.
• noResultsClass: The class to assign to the <li> list item that displays the no-results message.
• noResultsMessage: If undefined, the plugin will simply hide away the autocomplete dropdown if it couldn’t find any results. If you give it a value, however, it will display the dropdown populated with a single <li> list item populated with your message, with the class given in noResultsClass.
• onComplete: A callback method you supply that Awesomecomplete will call when the user completes something. The method will be called with the following params:
  

  var onComplete = function(dataItem)
  {
    // dataItem is the JavaScript data object handed to Awesomecomplete as data that was ultimately chosen by the user.
  };

• splitTerm: Whether to consider the search term the user gives a single term or not. For instance, if you have a data item “Michael Scott”, and the user types “mic ott” with splitTerm on, it will match “Michael Scott”. However, if you turn this off, the same result won’t match because the data doesn’t literally contain the phrase “mic ott”.
• staticData: An array of JavaScript objects that represent the data you want to autocomplete on. For instance, here’s a bit of my test data from the example page:
  

  var mockData = [
    { name: 'Oscar Filippelli', email: 'oscar.filippelli@scranton.dundermifflin.com', phone: '(181) 640-7558' },
    { name: 'Kevin Palmer', email: 'kevin.palmer@yonkers.dundermifflin.com', phone: '(370) 756-3871' },
    { name: 'Kelly Bratton', email: 'kelly.bratton@yonkers.dundermifflin.com', phone: '(779) 742-2016' }
  ];

  
  And of course, the beauty of this plugin is that it completely doesn’t care what your data object looks like — it will search it all! It’s also pretty smart about things to avoid (nested objects, functions, arrays), but if it’s giving you trouble you can use the aforementioned @ dontMatch@ configuration to set things right again.
  Another thing to note here is that even if you give the plugin static data, if you also give it a dataMethod, it will favor that over this.
• suggestionListClass: This is the css class to assign to the <ul> list object that contains all the autocomplete goodness.
• renderFunction: This is the function that you can give the plugin to specify how, exactly, you want to render the <li> list items themselves in the suggestions. The params you get can seen in the following sample code, which just happens to be the default render function:
  

  var defaultRenderFunction = function(dataItem, topMatch, originalData)
  {
      return '<p class="title">' + dataItem['name'] + '</p>' +
             '<p class="matchRow"><span class="matchedField">' + topMatch + '</span>: ' +
              dataItem[topMatch] + '</p>';
  };

  
  As you can see, we get a dataItem back, which is the JavaScript data object out of the array of data you passed in that was a match, and you are currently rendering. If you have highlightMatches set to on, you’ll actually be getting back a copy of your data object, with your data fields stringified and matches wrapped in <span> tags.
  The topMatch is the name of the field that produced the best match. You can do with this whatever you will, or just don’t even declare it in your function declaration argument list to completely ignore it.
  There is also an originalData param — this is of course also optional so you don’t even have to declare it in your list, but should you have a burning desire to get at your original, unscathed, unhighlighted data object, it is provided here for you.
• resultLimit: The maximum number of results to display in the list.
• typingDelay: The number of milliseconds to wait after the last keystroke before the plugin goes looking for data. I would leave this at 0 if you have passed in prefetched data via staticData, but otherwise you’ll want to set this to around 100-250ms to prevent a flood of callbacks to your server, depending on how much you trust your users’ typing abilities. Well, and your server.
• valueFunction: Similar to the renderFunction, but this one specifies how to render the text that actually appears in the textbox after the user chooses one of the autocomplete suggestions. The default one is pretty boring and useless — it just outputs whatever data was in your specified nameField. The following example shows you the valueFunction used by the provided example code, which renders a person object into an email name:
  

  var valueFunction = function(dataItem) {
    return dataItem['name'] + ' <' + dataItem['email'] + '>';
  };

  
  The only argument you get here is the original JavaScript data object that the autocomplete suggestion in question entails. Really, it’s all you should need.
• wordDelimiter: A RegExp pattern specifying what to split the search term along, should you enable splitTerm. By default, it is /[^\da-z]+/ig, which more or less considers any non-alphanumeric character to be a non-word character. You should do your best here to avoid generating empty terms when the string is split (it’s literally a String.split()), though the plugin will do its best to cope anyway.