Autocomplete enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.

The widget is based on popular jQuery UI Autocomplete widget, but it brings some advanced built-in features:

  • caching
  • tokenizing
  • using DOM as a source of suggestions
  • auto-fill
  • built-in button




Closes the Autocomplete menu. Useful in combination with the search method, to close the open menu.



Removes the autocomplete functionality completely. This will return the element back to its pre-init state.



Disables the autocomplete.



Enables the autocomplete.



option( optionName )

Gets an object containing key/value pairs representing the current autocomplete options hash.


Gets an object containing key/value pairs representing the current autocomplete options hash.

option( optionName, value )

Sets the value of the autocomplete option associated with the specified optionName.

option( options )

Sets one or more options for the autocomplete.



Returns a jQuery object containing the menu element. Although the menu items are constantly created and destroyed, the menu element itself is created during initialization and is constantly reused.




Which element the menu should be appended to. When the value is null, the parents of the input field will be checked for a class of ui-front. If an element with the ui-front class is found, the menu will be appended to that element. Regardless of the value, if no element is found, the menu will be appended to the body.

Default: null



Auto filling mode previews a selected suggestion in the input as a user types.

Default: false



Auto focusing mode selects first suggestion in a list once it appears, so user can just confirm it using enter key.

Default: false



Turns suggestions caching on.

In caching mode, autocomplete first tries to look suggestions for given term up in cache given by cacheImplementation option and if no suggestions are found, autocomplete uses classic source to retrieve suggestions.

Default: false



Allows to plug in implementation of cache, which in turn allows to use stores like Local Storage for remembering values.

cacheImplementation is an class with two methods:

  • function get(searchTerm) - returns all cached suggestions for given searchTerm prefix
  • function set(searchTerm, suggestions) - stores all provided suggestions into cache under given searchTerm prefix

Default: $.rich.autocomplete.ObjectCache



Function that determines what prefix of search term will be used to query a cache:

function cachePrefixExtract(searchTerm) - default implementation extracts first minLength characters of a search term

Default: $.rich.autocomplete.cachePrefixExtract



The delay in milliseconds between when a keystroke occurs and when a search is performed. A zero-delay makes sense for local data (more responsive), but can produce a lot of load for remote data, while being less responsive.

Default: 0



Disables the autocomplete if set to true.

Default: false



Provide function which will be used to filter array of suggestions by given searchTerm:

function filter(array, searchTerm)



The minimum number of characters a user must type before a search is performed. Zero is useful for local data with just a few items, but a higher value should be used when a single character search could match a few thousand items.

Default: 0



Identifies the position of the suggestions menu in relation to the associated input element. The of option defaults to the input element, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the various options.

Default: `{ my: "left top", at: "left bottom", collision: "none" }`



Allows to append a button to the input to allow opening suggestion box by mouse.

Default: false



Defines the data to use, must be specified.

Multiple types supported:

  • Array: An array can be used for local data.There are two supported formats:

    • An array of strings: [ "Choice1", "Choice2" ]
    • An array of objects with label and value properties: [ { label: "Choice1", value: "value1" }, ... ]

      The label property is displayed in the suggestion menu. The value will be inserted into the input element when a user selects an item. If just one property is specified, it will be used for both, e.g., if you provide only value properties, the value will also be used as the label.

  • String: When a string is used, the Autocomplete plugin expects that string to point to a URL resource that will return JSON data. It can be on the same host or on a different one (must provide JSONP). The Autocomplete plugin does not filter the results, instead a query string is added with a term field, which the server-side script should use for filtering the results. For example, if the source option is set to "" and the user types foo, a GET request would be made to The data itself can be in the same format as the local data described above.

  • Function: The third variation, a callback, provides the most flexibility and can be used to connect any data source to Autocomplete. The callback gets two arguments:

    • A request object, with a single term property, which refers to the value currently in the text input. For example, if the user enters "new yo" in a city field, the Autocomplete term will equal "new yo".
    • A response callback, which expects a single argument: the data to suggest to the user. This data should be filtered based on the provided term, and can be in any of the formats described above for simple local data. It's important when providing a custom source callback to handle errors during the request. You must always call the response callback even if you encounter an error. This ensures that the widget always has the correct state.

      When filtering data locally, you can make use of the built-in $.ui.autocomplete.escapeRegex function. It'll take a single string argument and escape all regex characters, making the result safe to pass to new RegExp().



Allows to repeat auto-completion several times by using separator between words.

You can provide multiple tokens.

Default: null



Triggered when the field is blurred, if the value has changed.


Triggered when the menu is hidden. Not every close event will be accompanied by a change event.


Triggered when the autocomplete is created.


Triggered when focus is moved to an item (not selecting). The default action is to replace the text field's value with the value of the focused item, though only if the event was triggered by a keyboard interaction. Canceling this event prevents the value from being updated, but does not prevent the menu item from being focused.


Triggered when the suggestion menu is opened or updated.


Triggered after a search completes, before the menu is shown. Useful for local manipulation of suggestion data, where a custom source option callback is not required. This event is always triggered when a search completes, even if the menu will not be shown because there are no results or the Autocomplete is disabled.


Triggered when an item is selected from the menu. The default action is to replace the text field's value with the value of the selected item. Canceling this event prevents the value from being updated, but does not prevent the menu from closing.


Triggered when search is triggered but before raw suggestions are parsed/processed.

It gives chance to update source of suggestions as reflection to current search term.

function update(request [, doneCallback])

  • request is object which contains search term: { term: 'searchTerm' }
  • when doneCallback is provided, widget will wait until doneCallback is called. Usually it is called on the end of AJAX data update.