AutoCompleteJS » Documentation

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

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

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.