bootstrap autocomplete
Autocomplete

Bootstrap 4 autocomplete dropdown

Dec 04, 2020 

Read bootstrap 4 autocomplete dropdown for more information.

 

bootstrap autocomplete
Contents hide
1. Features
2. Getting Started
3. Basic usage
4. Text Autocomplete
5. Response Format
6. Select Autocomplete
7. Response Format for Select
8. Events
9. Reference
10. Activating Autocomplete
11. Configuration options
12. Advanced usage
13. Set custom value
14. Customize results using default AJAX resolver
15. Translating messages
Features
  • Fast.
  • Easy. No complex configuration. HTML attributes supported.
  • Modals supported. No problems in modals.
  • Customizable. You can customize every single step in the suggesting workflow.
  • Batteries included. It works out of the box for Bootstrap v3 and v4.
  • i18n. Use data-* attributes to specify the strings to use in case of errors/noresults.
  • Styles. No custom styles. Uses standard Bootstrap’s dropdown.
bootstrap 4 autocomplete dropdown

Build a search with autocomplete without any coding

Getting Started

Bootstrap Autocomplete works as a plugin. Add it to your page

<script src="bootstrap-autocomplete.min.js"></script>

Using CDN (thanks to JSDelivr)

STABLE version 2.3.0
<script src="https://cdn.jsdelivr.net/gh/xcash/bootstrap-autocomplete@v2.3.0/dist/latest/bootstrap-autocomplete.min.js"></script>
Latest version (this is the development branch)
<script src="https://cdn.jsdelivr.net/gh/xcash/bootstrap-autocomplete@master/dist/latest/bootstrap-autocomplete.min.js"></script>

That’s it! Go on to enhance your text fields! 🙂

Basic usage
Text Autocomplete

Autocomplete is not enabled by default. You must activate it in the fields you want to enhance. Of course, you can also use a wide selector to enable it on specific classes or tags.

Suppose you have a field as follows

<input class="form-control basicAutoComplete" type="text" autocomplete="off">

Here the class basicAutoComplete is used to identify all the fields on which to activate a basic autocomplete. Then in Javascript we activate it.

$('.basicAutoComplete').autoComplete({
    resolverSettings: {
        url: 'testdata/test-list.json'
    }
});

In this example, we specified the URL to use. Autocomplete will automatically make an Ajax GET request to that URL using an argument named q with the text typed by the user. Rate limits are enforced and the minimum field length is 2.

Even simpler you can pass the URL directly in the markup

<input class="form-control basicAutoComplete" type="text"
        data-url="myurl"
        autocomplete="off">

and enhance it just with

$('.basicAutoComplete').autoComplete();
Response Format

We know how to start an autocomplete lookup but what about the results?

The default configuration expects a simple list in JSON format. Like

[
    "Google Cloud Platform",
    "Amazon AWS",
    "Docker",
    "Digital Ocean"
]
Select Autocomplete

One of the main features of Bootstrap Autocomplete is to enhance <select> fields as easy as <input> text fields. Selects are useful to restrict choices to a set of possibilities.

Enhancing a select is no different than text fields.

<select class="form-control basicAutoSelect" name="simple_select"
    placeholder="type to search..."
    data-url="testdata/test-select-simple.json" autocomplete="off"></select>
$('.basicAutoSelect').autoComplete();

Nice! 🙂

Response Format for Select

In this case, we need two values in the response: id and a text.

[
    { "value": 1, "text": "Google Cloud Platform" },
    { "value": 2, "text": "Amazon AWS" },
    { "value": 3, "text": "Docker" },
    { "value": 4, "text": "Digital Ocean" }
]

Events

Bootstrap Autocomplete triggers usual events.
change – Value changed

And custom.

autocomplete.select – (evt, item) The element item is the item selected by the user and currently selected in the field.

autocomplete.freevalue – (evt, value) The text field contains value as the custom value (i.e. not selected from the choices dropdown).

Reference
Activating Autocomplete
$(…).autoComplete([options])
Enhance the form fields identified by the selector

Arguments:

  • options – Configuration options of type ConfigOptions.

Configuration options

formatResult
callback(item)
Arguments:

  • item (object) – The item selected or rendered in the dropdown.

Returns:

An object { id: myItemId, text: myfancyText, html?: myfancierHtml }.

minLength
Default: 3. Minimum character length to start lookup.
autoSelect
Default: true. Automatically selects selected item on blur event (i.e. using TAB to switch to next field).
resolver
Default: ajax. Resolver type. custom to implement your resolver using events.
noResultsText
Default: No results. Text to show when no results found.
resolverSettings
Object to specify parameters used by default resolver.

url
Url used by default resolver to perform lookup query.
requestThrottling
Default: 500. Time to wait in ms before starting a remote request.
events
Object to specify custom event callbacks.

func(qry, callback, origJQElement)
Function called to perform a lookup.

Arguments:

  • qry (string) – Query string.
  • callback – Callback function to process results. Called passing the list of results callback(results).
  • origJQElement (JQuery) – Original jQuery element.
searchPost
func(resultsFromServer, origJQElement)
Function called to manipulate server response. Bootstrap Autocomplete needs a list of items. Use this function to convert any server response in a list of items without reimplementing the default AJAX server lookup.

Arguments:

  • resultsFromServer – Result received from the server. Using the default resolver this is an object.
  • origJQElement (JQuery) – Original jQuery element.

Returns:

List of items.

Following events are available to fine tune every lookup aspect. Rarely used in common scenarios

typed
func(newValue, origJQElement)
Field value changed. Use this function to change the searched value (like prefixing it with some string, filter some characters, …). Or to stop lookup for certain values.Arguments:

  • newValue (string) – New value.
  • origJQElement (JQuery) – Original jQuery element.

Returns:

(Un)modified value or false to stop the execution.

searchPre
func(newValue, origJQElement)
Before starting the search. Like in the typed event, this function can change the search value. The difference is this event is called after minLength checks.Arguments:

  • newValue (string) – New value.
  • origJQElement (JQuery) – Original jQuery element.

Returns:

(Un)modified value or false to stop the execution.

As a reference the lookup workflow calls events in the following order:

typed -> searchPre -> search -> searchPost
Advanced usage
Set custom value

To set an initial or change the value of the field.

$('.myAutoSelect').autoComplete('set', { value: myValue, text: myText });

Customize results using default AJAX resolver

Using the searchPost the event you can manipulate the result set making it compatible with autocomplete default. This is useful to bypass the customization of the entire search AJAX call.

$('.myAutoSelect').autoComplete({
    events: {
        searchPost: function (resultFromServer) {
            return resultFromServer.results;
        }
    }
});
Translating messages

To customize “no results” message use the following markup.

<select class="form-control emptyAutoSelect" name="empty_select"
    data-url="testdata/test-empty.json"
    data-noresults-text="Nothing to see here."
    autocomplete="off"></select>

Searches related to bootstrap 4 autocomplete dropdown

You may also like