Config Object

The Config Object initializes the AutoComplete widget.

You define your List Objects - which control which options are available to the user - on the lists property.

As a shorthand method, you can provide an array of Option Objects to the config object and it will be expanded as the default list for the widget. See the Simple List Example.

As another shorthand method, you can provide a single string value and AutoComplete assumes it's an AJAX url. See the Simple AJAX example.

Property / Type Required Default Description Example

initialList

String

sometimes n/a

The initialList property is the first list started when the user clicks on the AutoComplete widget.

It's value should be the name of a List Object.

initialList is required when there are more than one List Objects on config.lists.

Nested Lists 1

Nested Lists 3

initialValue

Array of
Token Groups

no n/a

If provided, sets the initial value of the AutoComplete widget.

initialValue

lists

Object of
List Objects

yes n/a

The lists property contains all of the lists used to power the dropdown options.

lists should be an object where the property values are the names of lists, and the values are List Objects.

Nested Lists 1

Nested Lists 3

maxTokenGroups

Number or
false

no false

The maximum number of Token Groups allowed in the search bar.

Set maxTokenGroups to false to allow unlimited Token Groups.

maxTokenGroups

onChange

Function

no n/a

Function to execute when the value of the widget changes.

The first argument to the function is the new value of the widget, the second argument is the old value of the widget.

If this function returns a valid widget value, then that value becomes the value of the widget. If not, the original new value becomes the value of the widget.

onChange - Basic Usage

onChange - Modify Value

placeholderHTML

String

no ''

A placeholder to show in the AutoComplete widget when there are no Token Groups.

placeholderHTML

showErrors

false or
String or
Function

no n/a

showErrors is an optional parameter to control how AutoComplete reports errors.

Every error in AutoComplete has a unique code to help diagnose problems and search for solutions.

If showErrors is false then errors will be ignored.

If showErrors is 'console' then errors will be sent to console.log().

If showErrors is 'alert' then errors will be sent to window.alert().

If showErrors is a function then the first argument is the unique error code, the second argument is an error string, and an optional third argument is a data structure that is relevant to the error.

showErrors console.log

showErrors alert

tokenSeparatorHTML

String or
Function

no ':'

The HTML string to put between Tokens in the search bar.

If tokenSeparatorHTML is a function the first argument is the Token Object to the left of the separator, the second argument is the Token Object to the right.

The function should return an HTML string.

tokenSeparatorHTML string

tokenSeparatorHTML function


List Object

list
Noun
A number of connected items or names written or printed consecutively, typically one below the other.

List Objects are the heart of the AutoComplete widget. They define the options available to the user when they are typing.

The options for a List Object can be sourced directly in the JavaScript or externally with AJAX.

You can define the list workflow using the children property on List Objects.

As a shorthand method, you can provide an array of Option Objects anywhere that expects a full List Object. See the Nested Lists example.

As another shorthand method, you can provide a single string value and AutoComplete assumes it's an AJAX url. See the Nested Lists with AJAX example.

Property / Type Required Default Description Example

ajaxErrorHTML

String or
Function

no 'AJAX Error'

An HTML string to display when an AJAX request has failed.

If ajaxErrorHTML is a function, the first argument is the type of error that has occurred, the second argument is the text that the user has entered, and the third argument is the current value of the AutoComplete widget.

Possible values for the first argument are: 'timeout', 'error', and 'parsererror'. Note: you will never see 'abort', as this is handled internally by AutoComplete.

The function should return an HTML string.

ajaxErrorHTML string

ajaxErrorHTML function

ajaxLoadingHTML

String or
Function

no 'Searching
…'

An HTML string to display when searching for options.

If ajaxLoadingHTML is a function, the first argument is the text that the user has entered and the second argument is the current value of the AutoComplete widget.

The function should return an HTML string.

ajaxLoadingHTML string

ajaxLoadingHTML function

ajaxOpts

Object or
Function

no n/a

Internally, AutoComplete uses the jQuery $.ajax() method to make AJAX requests.

If provided, ajaxOpts will be called with $.extend() against the default settings.

You can override any $.ajax() parameter except: async, complete, error, statusCode, success (ie: parameters that effect control flow)

If ajaxOpts is a function the first argument is the text that the user has typed and the second argument is the current value of the AutoComplete widget.

The function should return an object to pass to $.ajax().

AJAX using POST

AJAX with preProcess function

ajaxOpts.preProcess

Function

no n/a

preProcess is an optional function that will be called after the AJAX request has finished and before the options are shown.

The first argument is the data returned by the server, the second argument is the text that the user has entered, and the third argument is the current value of the AutoComplete widget.

The function should return an array of Option Objects.

preProcess is independent of the jQuery $.ajax() method.

AJAX with preProcess function

ajaxOpts.url

String or
Function

no n/a

The url to send an AJAX request to.

The string '{input}' will be replaced with the text the user has typed.

The text will be escaped using encodeURIComponent().

If url is a function, the first argument is the text that the user has typed and the second argument is the current value of the AutoComplete widget.

The function should return a url string.

AJAX with local Options

allowFreeform

Boolean

no false

If true, allows the user to enter free-form text in the search bar.

If false, the user must select an option from the dropdown list.

There can still be options when allowFreeform is set to true, but the user does not have to select one.

Basic allowFreeform

allowFreeform Multiple Lists

cacheAjax

Boolean

no false

If true, AutoComplete will cache the results of AJAX calls to localStorage using the url as the key.

If false, it will not cache and send a new AJAX request every time.

Only HTTP GET requests are cached.

If the browser does not support localStorage it will only cache results for the duration of the page.

If you need to support browsers that do not have localStorage I recommend using a polyfill.

cache AJAX

cacheAjaxSeconds

Number or
false

no 1209600
(2 weeks)

Length of time in seconds to keep results in the cache.

Set cacheAjaxSeconds to false to cache results indefinitely.

cacheAjaxSeconds has no effect if cacheAjax is false.

cache AJAX length

children

String

no n/a

children should be the name of a List Object defined on config.lists.

When any option from the list is selected from the dropdown, children is the name of the next list to show in the dropdown.

If there is a children property on the Option Object selected it will supersede this children property.

children on List Object

Nested Lists 2

children override on Option Object

highlightMatches

Boolean

no true

If true, AutoComplete will highlight letter matches between what the user has typed and which options have matched.

This option programmatically changes the optionHTML value by adding <strong> tags around matching characters.

It tries to not replace letters that are inside HTML tags or special HTML characters, but if you have complicated or invalid HTML markup in your optionHTML it may not highlight correctly.

highlightMatches is independent of the matching algorithm used.

matchOptions

Function

no n/a

matchOptions is an optional function you can include to determine which options get shown in the dropdown when the user is typing.

The first argument to the function is the text that the user has entered, the second argument are the Option Objects matched by the default algorithm, the third argument is an array of all Option Objects for the current list, and the fourth argument is the current value of the AutoComplete widget.

The function should return an array of Option Objects.

You can return an array of any Option Objects from this function. They do not have to come from the existing Option Objects in the list.

This function gets executed with every 'keydown' event on the input element so it's in your best interest to make this function as fast as possible.

matchOptions

noResultsHTML

String or
Function

no 'No results found.'

An HTML string to display when there are no options to show.

If noResultsHTML is a function, the first argument is the text that the user has entered and the second argument is the current value of the AutoComplete widget.

The function should return an HTML string.

noResultsHTML will never be shown when allowFreeform is true.

optionHTML

String or
Function

no n/a

If optionHTML is a string, option value properties inside curly braces will be replaced with HTML-escaped values.

If optionHTML is a function the first argument is the option.

The function should return an HTML string.

If there is an optionHTML property on the Option Object selected it will supersede this optionHTML property.

optionHTML string

optionHTML and tokenHTML as functions

tokenHTML

String or
Function

no n/a

If tokenHTML is a string, option value properties inside curly braces will be replaced with HTML-escaped values.

If tokenHTML is a function the first argument is the option.

The function should return an HTML string.

If there is a tokenHTML property on the option selected it will supersede this tokenHTML property.

optionHTML and tokenHTML as functions

options

Array of Option Objects

no []

options is an array of Option Objects that determine which options to show in the dropdown for this list.


Option Object

option
Noun
A thing that is or may be chosen.

Option Objects are the meat of the AutoComplete widget. They are the options displayed to the user as they type.

Option Objects can hold any arbitrary value; they are not limited to what the user sees on the screen.

An Option Object becomes a Token Object when the user selects it from the dropdown list.

You can define the list workflow using the children property on Option Objects.

As a shorthand method, you can use a string as an Option Object. See the allowFreeform example.

Property / Type Required Default Description Example

children

String or
false

no n/a

children should be the name of a List Object defined on config.lists.

When any option from the list is selected from the dropdown, children is the name of the next list to show in the dropdown.

If children is false, the list workflow stops when the option is selected.

This children property will supersede a children property on the parent List Object.

Nested Lists 1

Nested Lists 2

children override on Option Object

optionHTML

String

no n/a

An HTML string to show inside the dropdown.

This optionHTML property will supersede an optionHTML property on the parent list.

If there is no optionHTML on the option and there is no optionHTML on the parent list and value is a string, then optionHTML gets an HTML-escaped value.

tokenHTML

String

no n/a

An HTML string to show inside the search bar.

This tokenHTML property will supersede a tokenHTML property on the parent list.

If there is no tokenHTML on the option and there is no tokenHTML on the parent list, then tokenHTML gets the value of optionHTML.

value

String or
Number or
Array or
Object

yes n/a

value is what gets saved in the Token Object when the user selects the option from the dropdown list.

value can be anything that is safe to call JSON.stringify() on.


Token Object

token
Noun
A thing serving as a visible or tangible representation of something abstract.

Token Objects are what is stored on the search bar when a user selects an option from the dropdown menu.

A Token Group is an array of Token Objects.

The value of the search bar is an array of Token Groups.

Token Objects are not explicitly defined in the AutoComplete config; they are created from an Option Object using the option.value and option.tokenHTML properties.

You can use a string as shorthand for a Token Object when using the setValue method.

Property / Type Required Default Description Example

tokenHTML

String

yes n/a

tokenHTML is the HTML displayed in the search bar for the token.

It comes from the option.tokenHTML property.

optionHTML and tokenHTML as functions

value

String or
Number or
Array or
Object

yes n/a

value is any JSON.stringify()-able data structure.

It comes from the option.value property.

getValue


Methods

Each AutoComplete object has methods you can use to interact with the widget.

Method Args Description Example
addOption(name, option)

name - name of the list to add the option to

option - Option Object to add to the list

Add an option to a List Object.

Returns true if adding the option was successful.

Returns false otherwise.

addOption

blur() none

Remove focus from the widget.

blur

Simulate User Input

clear() none

Clear the value of the widget.

Has the same effect as calling setValue([])

clear

destroy() none

Remove the widget from the DOM.

destroy

focus() none

Puts the input focus on the widget.

focus

getList(name)

name - name of the list to get

Returns the List Object if it exists.

Returns false if the list does not exist.

getList

getLists() none

Returns an object of all the List Objects.

getLists

getValue() none

Returns the current value of the widget.

Returns an empty array if the widget has no Token Groups.

getValue

list(name)

name - name of the list to get

Alias of getList(name)

list(name, list)

name - name of the list to add or update

list - List Object

Alias of setList(name, list)

pressDown() none

Simulates the user pressing the "Down Arrow" key on the input field.

Has no effect if the input field does not have focus.

Simulate User Input

pressEnter() none

Simulates the user pressing the "Enter" key on the input field.

Has no effect if the input field does not have focus.

Simulate User Input

pressUp() none

Simulates the user pressing the "Up Arrow" key on the input field.

Has no effect if the input field does not have focus.

Simulate User Input

removeList(name)

name - name of the list to remove

Returns true if the list was removed.

Returns false if not.

You cannot remove the initialList.

removeList

removeTokenGroup(index)

index - zero-based index of the Token Group to remove

Remove a Token Group by array index.

Returns the updated value of the widget if successful.

Returns false otherwise.

removeTokenGroup

setInput(input)

input - text to set the input element to

Puts text into the input element as if the user had typed it.

Returns true and updates the widget if updating the input was successful.

Returns false otherwise.

Simulate User Input

setList(name, list)

name - name of the list to add or update

list - List Object

Adds a new list or updates an existing list.

Returns true if adding the list was successful.

Returns false otherwise.

setValue(value)

value - array of Token Groups

Returns true and updates the widget if value is valid.

Returns false otherwise.

setValue

val() none

Alias of getValue()

val(value)

value - array of Token Groups

Alias of setValue(value)


Errors

AutoComplete has an error system designed to inform you when you use the API incorrectly.

Every alert has a unique code associated with it and you can control how the errors are presented with the showErrors config option.

Error ID Error Text More Information
1002 Element with id "<id>" does not exist in the DOM.

AutoComplete could not find your element with document.getElementById.

Please note that if you pass a string as the first argument to the AutoComplete() constructor it should be the value of a DOM id, not a CSS selector (ie: "search_bar", not "#search_bar").

1003 JSON does not exist. Please include a JSON polyfill.

AutoComplete requires a JSON implementation. Please include a polyfill for older browsers.

1004 Unable to find a valid version of jQuery. Please include jQuery 1.4.2 or higher on the page.

AutoComplete requires jQuery version 1.4.2 or higher.

1005 You must include at least one List Object on lists.

The lists config is mandatory and must include at least one List Object.

1037 The first argument to AutoComplete() cannot be an empty string.

The first argument to the AutoComplete() constructor should be the id of a DOM element or a reference to a single DOM element.

1044 The first argument to AutoComplete() must be an ID or a single DOM node.

The first argument to the AutoComplete() constructor should be the id of a DOM element or a reference to a single DOM element.

1273 You cannot include properties that effect control flow on ajaxOpts: "async", "complete", "error", "statusCode", "success"

You are not allowed to override certain AJAX properties.

See ajaxOpts.

1328 Error in removeList method. List "<listName>" does not exist.

The list name you provided to the removeList method is not defined on lists.

1424 Error in removeList method. You cannot remove the initialList "<listName>"

You are not allowed to remove the initialList.

2231 The first argument to the removeList method must be a non-empty string.

The first argument to removeList should be the name of a List Object that is defined on lists.

2535 The list object for list "<listName>" is invalid.

The structure of your List Object is invalid.

2642 You cannot use an empty string for a list name.

It is valid to use an empty string for an object property name in JavaScript, but this is not allowed by AutoComplete.

2728 initialList "<listName>" does not exist on the lists object.

The list you specified on initialList is not defined on lists.

2732 The list object passed to the setList method is not valid.

The structure of your List Object is invalid.

2789 The first argument to the getList method must be a non-empty string.

The first argument to getList should be the name of a List Object that is defined on lists.

3193 Could not find a valid value for optionHTML. Resorted to using value property "<propertyName>"

AutoComplete could not find a valid optionHTML on either the Option Object or the List Object so it resorted to using the first string option.value property it could find.

3776 Invalid Value returned from your custom onChange function.

If you specify an onChange function, it must return an array of Token Groups.

3843 optionHTML function did not return a string.

If you provide a function for optionHTML it must return an HTML string.

4823 Error in removeTokenGroup method. Token group index "<tokenGroupIndex>" does not exist.

You tried to remove a Token Group array index which doesn't exist.

4922 The first argument to the setInput method must be a string.

The argument passed to setInput must be a string.

5732 Error in addOption method. List "<listName>" does not exist.

The list name you provided to the addOption method is not defined on lists.

5783 Unable to create HTML string for optionHTML.

This is an internal AutoComplete error that you should never see.

If you see this error please open a GitHub issue.

5938 Wrong number of arguments passed to list method.

The list method takes either 1 or 2 arguments.

6447 Invalid value pass to initialValue.

The value passed to initialValue must be an array of Token Groups.

6823 Invalid value passed to the setValue method.

The value passed to the setValue method must be an array of Token Groups.

7283 The first argument to the setList method must be a non-empty string.

The first argument to setList should be the name of a List Object that is defined on lists.

7887 Invalid option passed to addOption method.

You must pass a valid Option Object to the addOption method.

7998 Your tokenSeparatorHTML function did not return a string.

If you provide a function to tokenSeparatorHTML, it must return a string.

8292 Could not find optionID "<optionId>".

This is an internal AutoComplete error that you should never see.

If you see this error please open a GitHub issue.

8366 The first argument to the addOption method must be a non-empty string.

The list name you provided to the addOption method is not defined on lists.

8721 AJAX url must be a string. Did you forget to include one on ajaxOpts?

If you provide a custom function on ajaxOpts.url, it must return a valid URL string.

9992 Wrong number of arguments passed to val method.

The val method takes either 0 or 1 arguments.