Skip to content
Switch branches/tags

Ajax Bootstrap Select GitHub version Build Status CDNJS Gitter FOSSA Status

Getting Started

Extends existing Bootstrap Select implementations by adding the ability to search via AJAX requests as you type. Originally for CROSCON.


Minimum requirements:

Bootstrap Select must either be be initialized with liveSearch enabled in the passed options or the select element must have the data-live-search="true" attribute.

This plugin must be initialized after Bootstrap Select has been initialized. For a more detailed explanation on implementation, see usage example.

Suggested requirements:


Options can be passed via data attributes or through the JavaScript options object. For data attributes, append the option name to the data-abs- prefix. Options names (and any nested options) are always lower case and separated by -, such as in data-abs-ajax-url="..." or data-abs-locale-search-placeholder="...".


Deprecated: Since version 1.2.0, see: options.preprocessData.

Type: Function



Type: Object

Data Attribute: data-abs-ajax[-*]="..."

The options to pass to the jQuery AJAX request.

    url: null, // Required.
    type: 'POST',
    dataType: 'json',
    data: {
        q: '{{{q}}}'


Type: Number

Default: 0

Data Attribute: data-abs-min-length="..."

Invoke a request for empty search values.


Deprecated: Since version 1.2.0, see: options.ajax.

Type: String


Type: String

Default: "keyup"

Data Attribute: data-abs-bind-event="..."

The event to bind on the search input element to fire a request.


Type: Boolean

Default: true

Data Attribute: data-abs-cache="..."

Cache previous requests. If enabled, the "enter" key (13) is enabled to allow users to force a refresh of the request.


Type: Boolean

Default: true

Data Attribute: data-abs-clear-on-empty="..."

Clears the previous results when the search input has no value.


Type: Boolean

Default: true

Data Attribute: data-abs-clear-on-error="..."

Clears the select list when the request returned with an error.


Deprecated: Since version 1.2.0, see: options.log.

Type: Boolean


Type: Boolean

Default: false

Data Attribute: data-abs-empty-request="..."

Invoke a request for empty search values.


Type: Object

Data Attribute: data-abs-ignored-keys[-*]="..."

Key codes to ignore so a request is not invoked with bindEvent. The "enter" key (13) will always be dynamically added to any list provided unless the "cache" option above is set to "true".

    9: "tab",
    16: "shift",
    17: "ctrl",
    18: "alt",
    27: "esc",
    37: "left",
    39: "right",
    38: "up",
    40: "down",
    91: "meta"


Type: String

Default: null

Data Attribute: data-abs-lang-code="..."

The language code to use for string translation. By default this value is determined by the browser, however it is not entirely reliable. If you encounter inconsistencies, you may need to manually set this option.


Type: Object

Default: null

Data Attribute: data-abs-locale[-*]="..."

Provide specific overrides for locale string translations. Values set here will cause the plugin to completely ignore defined locale string translations provided by the set language code. This is useful when needing to change a single value or when being used in a system that provides its own translations, like a CMS.

locale: {
    searchPlaceholder: Drupal.t('Find...')


Type: String|Number|Number

Default: 'error'

Data Attribute: data-abs-log="..."

Determines the amount of logging that is displayed:

  • 0, false: Display no information from the plugin.
  • 1, 'error': Fatal errors that prevent the plugin from working.
  • 2, 'warn': Warnings that may impact the display of request data, but does not prevent the plugin from functioning.
  • 3, 'info': Provides additional information, generally regarding the from request data and callbacks.
  • 4, true, 'debug': Display all possible information. This will likely be highly verbose and is only recommended for development purposes or tracing an error with a request.


Deprecated: Since version 1.2.0, see: options.preserveSelected.

Type: Boolean


Deprecated: Since version 1.2.0, see: locale.emptyTitle.


Type: Function|null

Default: function(){}

Process the raw data returned from a request. The following arguments are passed to this callback:

  • data - Array The raw data returned from the request, passed by reference. This callback must return one of the following:
  • Array - A new array of items. This will replace the passed data.
  • undefined|null|false - Stops the callback and will use whatever modifications have been made to data.
function (data) {
    var new = [], old = [], other = [];
    for (var i = 0; i < data.length; i++) {
        // Add items flagged as "new" to the correct array.
        if (data[i].new) {
        // Add items flagged as "old" to the correct array.
        else if (data[i].old) {
        // Something out of the ordinary happened, put these last.
        else {
    // Sort the data according to the order of these arrays.
    return [].concat(new, old, other).


Type: Boolean

Default: true

Data Attribute: data-abs-preserve-selected="..."

Preserve selected items(s) between requests. When enabled, they will be placed in an <optgroup> with the label Currently Selected. Disable this option if you send your currently selected items along with your request and let the server handle this responsibility.


Type: String

Default: 'after'

Data Attribute: data-abs-preserve-selected-position="..."

Place the currently selected options 'before' or 'after' the options returned from the request.


Type: Function|null

Default: function(){}

Process the data returned after this plugin, but before the list is built.


Type: Number

Default: 300

Data Attribute: data-abs-request-delay="..."

The amount of time, in milliseconds, that must pass before a request is initiated. Each time the options.bindEvent is fired, it will cancel the current delayed request and start a new one.


Type: Boolean

Default: false

Data Attribute: data-abs-restore-on-error="..."

Restores the select list with the previous results when the request returns with an error.


Type: Object

Data Attribute: data-abs-templates[-*]="..."

The DOM templates used in this plugin.

templates: {
    // The placeholder for status updates pertaining to the list and request.
    status: '<div class="status"></div>',

Locale Strings

See: options.locale


Type: String

Default: 'Currently Selected'

The text to use for the label of the option group when currently selected options are preserved.


Type: String

Default: 'Select and begin typing'

The text to use as the title for the select element when there are no items to display.


Type: String

Default: ''Unable to retrieve results'

The text to use in the status container when a request returns with an error.


Type: String

Default: 'Search...'

The text to use for the search input placeholder attribute.


Type: String

Default: 'Start typing a search query'

The text used in the status container when it is initialized.


Type: String

Default: 'No Results'

The text used in the status container when the request returns no results.


Type: String

Default: 'Searching...'

The text to use in the status container when a request is being initiated.


Type: String

Default: 'Please enter more characters'

The text used in the status container when the request returns no results.

JSON Results

The plugin expects a certain result structure, an array of objects with the objects following a certain structure, below is an example with every option set:

        value: 'string',    // Required.
        text: 'string',     // If not set, it will use the value as the text.
        class: 'string',    // The CSS class(es) to apply to the option element.
        disabled: false,     // {Boolean} true|false

        // NOTE: If "divider" is present as a property, the entire item is
        // considered a divider and the rest of the item value/data is
        // ignored. Alternatively, this can be set in the data property as well.
        divider: true,

        // Data attributes that you would set on the option tag, these will be
        // set on the newly created options tags and the selectpicker plugin
        // will process them accordingly.
        data: {
            divider: true,
            subtext: 'string',
            icon: 'class-name', // Icon class name ex: icon-glass
            content: '<div class="custom-class">my value label</div>',

Usage Example

        liveSearch: true
        ajax: {
            url: '/server/path/to/ajax/results',
            data: function () {
                var params = {
                    q: '{{{q}}}'
                    params.GroupID = gModel.selectedGroup().ContactGroupID;
                return params;
        locale: {
            emptyTitle: 'Search for contact...'
        preprocessData: function(data){
            var contacts = [];
                var len = data.Contacts.length;
                for(var i = 0; i < len; i++){
                    var curr = data.Contacts[i];
                            'value': curr.ContactID,
                            'text': curr.FirstName + ' ' + curr.LastName,
                            'data': {
                                'icon': 'icon-person',
                                'subtext': 'Internal'
                            'disabled': false
            return contacts;
        preserveSelected: false


Copyright (c) 2019 Adam Heim, contributors.
Released under the MIT license

FOSSA Status