Setup

This plugin requires only jQuery 1.12.4 and jQuery UI 1.10 (or any newer versions).
It can be initialized on a text box and options can be changed at any time the same way. If your list array contains objects, any objects that don't have the property matching displayProperty won't be shown in the search list.

// object collections or string arrays
$('#myTextBox').autoSuggestList({
  list: { 
    { id: 1, value: 'one',   otherProp: 'random' }, 
    { id: 2, value: 'two',   otherProp: 'random' },
    { id: 3, value: 'three', otherProp: 'random', tag: 'lucky' }
  },
  displayProperty: 'value'
});

$('#myTextBox').autoSuggestList({
  list: ['one', 'two', 'three'];
});

Setting Options

These are the options you can set. All of them can be changed at any time.

$('#myTextBox').autoSuggestList({
  list: [],                   // required - can hold strings or json objects
  displayProperty: '',        // the object's property name to display in the list
  
  // defaults                 
  minSearchChars: 0,          // minimum characters needed to trigger a search
  searchDelay: 0,             // delay in ms before searches are triggered
  matchCase: false,           // sets the search matching to be case sensitive
  showFullListOnFocus: true,  // show the full list when the textbox is focused, regardless of its value
  autoSelectFirst: false,     // auto highlight the first item in the list
  autoSelectOnly: true,       // auto highlight the item when there is only one in the list
  
  // delay in ms of item highlight scroll when holding arrow keys (0 for the browser's default behavior)
  // useful if you want to make the scroll speed with arrow keys very fast or very slow
  arrowHoldScrollInterval: 0, 
  
  // **extra css properties to apply to the list box**
  // applied to listbox div
  divCss: {},                 // css object of properties   ex: { backgroundColor: 'gray', color: 'black' }
  divClasses: '',             // space separated string of classes   ex: { 'my-class another-class' }
  // applied to ul element
  ulCss: {},                  // css object of properties 
  ulClasses: '',              // space separated string of classes
  // applied to li elements containing list items
  liCss: {},                  // css object of properties 
  liClasses: '',              // space separated string of classes 
  // applied to the currently highlighted li element
  highlightCss: {},           // css object of properties 
  highlightClasses: ''        // space separated string of classes 
});

Applying CSS

The properties of the CSS objects passed as options will be merged with any previous properties that were added. You can clear them all by passing in an empty object {}, or clear individual properties you have set by setting them to empty string. The classes options are passed as strings which will be overwritten when changed.

$('#myTextBox').autoSuggestList({
  divCss: {
    backgroundColor: 'green',
    border: 3px solid black'
  },
  highlightClasses: 'class1 class2 class3'
});
// changing css options
$('#myTextBox').autoSuggestList({
  divCss: {
    backgroundColor: ''
  },
  highlightClasses: 'class1'
});
// divCss will still have border property, but the 'green' backgroundColor will be reset to original value
// highlightClasses will now only contain 'class1'

Default CSS

These are the default classes applied to the widget, contained in the stylesheet autoSuggestList.css. These classes will always be applied. You can change the styles by using the CSS related options in the next section, or by editing the stylesheet itself. When the list opens and is too long to show in the current window, its height is limited to just above the the bottom of the window. The default behavior is for the list to be the same width as the textbox. If you want to make the width smaller, you have to change it by setting it in the divCss option. This is because the widget sets min-width as an attribute, which will override any class settings relating to width. The widget avoids setting the min-width attribute if the divCss option contains any width properties.

.asl-div {
  background-color: white; 
  overflow-y: auto;
  border: 1px solid black;
  position: absolute;
  z-index: 9999;
}
.asl-ul {
  list-style-type: none;
  margin: 0;
  padding: 0;
}
.asl-li {
  padding: 2px 6px 2px 6px;
  text-align: left;  
  color: black;
}
.asl-highlight {
  background-color: #3399ff;
  cursor: default;
}

Changing Functionality

You can change the default behavior by providing your own functions. By default, the displayProperty is used to match the search text, and to display in the textbox when items are selected.
searchMatchCondition allows you to decide whether each item matches the search text. It's easy to write a custom search condition that handles changing options.
textBoxFormatter allows you to specify what value should be put in the textbox when an item is selected.
Within the scope of these functions, this refers to your textbox

// provide your own search and textbox value functions
$('#myTextBox').autoSuggestList({
  list: [{ name: 'Walter Payton', nickName: 'sweetness' }, /*{and so on..}*/ ],
  displayProperty: 'name',  
  searchMatchCondition: mySearchCondition,  
  textBoxFormatter: myFormatter
});

// executes for each item in your list when searches are performed
// return true to include the item in the search results, false to exclude it 
// this example searches both properties to determine a match
// the current value of the matchCase and displayProperty options is provided 
function mySearchCondition(item, searchText, matchCase, displayProperty) {  
  var name = item[displayProperty]; // useful if you want to react to a changing displayProperty 
  var nickName = item.nickName;     // or just access specific properties directly
  if (!matchCase) {
    name = name.toLowerCase();
    nickName = nickName.toLowerCase();
  }
  return name.indexOf(searchText) > -1 || nickName.indexOf(searchText > -1);
  // obj array default: return item[displayProperty].indexOf(searchText) > -1;
  // str array default: return item.indexOf(searchText) > -1;
}

// executes when an item is selected
// return the string value you would like to be put in the textbox when item is selected 
// if you don't return a string value, the textbox will not be filled 
// the current value of the displayProperty option is provided 
// this example fills the textbox with name and nickname
function myFormatter(item, displayProperty) {
  return item.name + ' (' + item.nickName + ')';
  // obj array default: return item[displayProperty];
  // str array default: return item;
}

Events

These are the events that you can listen to. Event handlers can also be passed as options. These events all contain their original events with the exception of when itemHighlighted is triggered by the autoSelectFirst or autoSelectOnly options. The original event in these cases is a custom event named autohighlight
- event: the name of the event prepended with asl-)
- item: the list object or string depending on the contents of your array.
Within the scope of these functions, this refers to your textbox

// handler provided as option
$('#myTextBox').autoSuggestList({  
  itemSelected: function(event, item) {}, 
  itemHighlighted: function(event, item) {},
  itemMouseenter: function(event, item) {}, // triggered before itemHighlighted
  itemMouseleave: function(event, item) {}
});
// event handler binding
$('#myTextBox').on('asl-itemselected', function(event, item) {});
$('#myTextBox').on('asl-itemhighlighted', function(event, item) {});
$('#myTextBox').on('asl-itemmouseenter', function(event, item) {});
$('#myTextBox').on('asl-itemmouseleave', function(event, item) {});

Destroying

This widget can be disposed of properly by passing 'destroy'. This example will check to see if the widget is present before attempting to destroy it.

// data attribute name includes the namespace - sayel
if ($('#myTextBox').data('sayelAutoSuggestList')) {
  $('#myTextBox').autoSuggestList('destroy');
}

Enter settings and click Apply to test them!
Remove the widget by clicking Destroy

`list`: people states	`autoSelectFirst`:	`minSearchChars`:
`displayProperty`:	`showFullListOnFocus`:	`searchDelay`:
`matchCase`:	`autoSelectOnly`:	`arrowHoldScrollInterval`:

Including your own functions: (leave empty for default behavior)

$('#myTextBox').autoSuggestList({
  searchMatchCondition: mySearchCondition,  
  textBoxFormatter: myFormatter  
});

// remember searchText enters this function with same capitalization as entered in textbox
function mySearchCondition(item, searchText, matchCase, displayProperty) {

function myFormatter(item, displayProperty) {

Lists

These are the lists that can be used in this demo:

var people = [
  {id: 1, name: 'Fry', phone: '555-555-1111', tag: true},
  {id: 2, name: 'Leela', phone: '555-555-2222'}, 
  {id: 3, name: 'Bender', phone: '110-001-0110', tag: "let's go already!"}, 
  {id: 4, name: 'Amy', phone: '555-555-4444'},
  {id: 5, name: 'Zoidberg', phone: '555-555-5555'}, 
  {id: 6, name: 'Farnsworth', phone: '555-555-6666', tag: 'good news, everyone'}, 
  {id: 7, name: 'Hermes', phone: '555-555-7777', tag: 'my manwich!'}, 
  {id: 8, name: 'Scruffy', phone: '555-555-0000'}, 
  {id: 9, name: 'Zapp', phone: '555-555-8888'}, 
  {id: 10, name: 'Kif', phone: '555-555-9999'}, 
  {id: 11, name: 'Morbo', phone: '555-555-1234'}, 
  {id: 12, name: 'Calculon', phone: '555-555-5678'}, 
  {id: 13, name: 'Elzar', phone: '555-555-3333'}
];
  
var states = [
  'Alabama','Alaska','Arizona','Arkansas','California','Colorado','Connecticut',
  'Delaware','Florida','Georgia','Hawaii','Idaho','Illinois','Indiana','Iowa',
  'Kansas','Kentucky','Louisiana','Maine','Maryland','Massachusetts','Michigan',
  'Minnesota','Mississippi','Missouri',,'Montana','Nebraska','Nevada',
  'New Hampshire','New Jersey','New Mexico','New York','North Carolina',
  'North Dakota','Ohio','Oklahoma','Oregon','Pennsylvania','Rhode Island',
  'South Carolina','South Dakota','Tennessee','Texas','Utah','Vermont',
  'Virginia','Washington','West Virginia','Wisconsin','Wyoming'
];

Initialization

This is the initialization for this demo.

$('#myTextBox').autoSuggestList({
  list: people,
  displayProperty: 'name',
  // demo defines showOutput() to listen to and display event info above textbox
  itemSelected: showOutput, 
  itemMouseenter: showOutput,  
});

AutoSuggestList

A jQuery plugin to attach an auto suggestion dropdown list to a text box

Download: https://github.com/sayelr/AutoSuggestList