Fork me on GitHub

Bootstrap Multiselect

Bootstrap Multiselect is a JQuery based plugin to provide an intuitive user interface for using select inputs with the multiple attribute present. Instead of a select a bootstrap button will be shown as dropdown menu containing the single options as checkboxes.

Note: The option names may have changed due to the latest updates.

Getting Started

The following code snippet will help you getting started. 

<!-- Include Twitter Bootstrap and jQuery: -->
<link rel="stylesheet" href="css/bootstrap.min.css" type="text/css"/>
<script type="text/javascript" src="js/jquery.min.js"></script>
<script type="text/javascript" src="js/bootstrap.min.js"></script>

<!-- Include the plugin's CSS and JS: -->
<script type="text/javascript" src="js/bootstrap-multiselect.js"></script>
<link rel="stylesheet" href="css/bootstrap-multiselect.css" type="text/css"/>

<!-- Build your select: -->
<select class="multiselect" multiple="multiple">
  <option value="cheese">Cheese</option>
  <option value="tomatoes">Tomatoes</option>
  <option value="mozarella">Mozzarella</option>
  <option value="mushrooms">Mushrooms</option>
  <option value="pepperoni">Pepperoni</option>
  <option value="onions">Onions</option>
</select>

<!-- Initialize the plugin: -->
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect();
  });
</script>

Examples

The best way learning from the examples is using firebug, chrome developer tools or similar tools for your browser. Examine the generated markup and used javascript code.

Normal select. The plugin will do single selection using radio buttons rather than multiple selection using checkboxes.
Select with preselected options: <option value="cheese" selected>Cheese</option>
Multiselect with a 'Select all' option
Multiselect with a 'Select all' option and filtering enabled using the enableFiltering option.
As link using buttonClass: 'btn btn-link'.
Small button using buttonClass: 'btn btn-default btn-sm'.
Multiple select within a group with add-ons and default container for the plugin: buttonContainer: '<div class="btn-group" />'.
Using the onChange option you can add an event handler to the change event. The event handler gets the selected option as first parameter and a variable saying whether the option is checked or not as second one.
For long option lists the maxHeight option can be set.
The plugin supports disabled options, too: disabled="disabled"
Use the buttonWidth option to adjust the width of the button.
Using the onChange option to prevent user from deselecting selected options.
Option groups are detected automatically and for each option group an header element is added: <optgroup label="Mathematics">...</optgroup>
Option groups and options without any group are supported simultaneously.
Using the selectedClass option to turn off the active class for selected options.
Specifiy an alternaitve label for the options: <option label="label"></option>
Make the menu drop right instead of dropping left with dropRight.
Using the data-role="multiselect" attribute for automatic wireup.
The multiselect will adopt the state of the select: <select disabled></select>.
The button will keep the tabindex of the select.

Options

Option Explanation Usage
buttonText A function returning the string displayed if options are selected. All currently selected options and the select are passed as argument. In addition HTML can be added to the button, for example the caret icon seen in the examples. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      buttonText: function(options, select) {
        if (options.length == 0) {
          return this.nonSelectedText + ' <b class="caret"></b>';
        }
        else {
          if (options.length > this.numberDisplayed) {
            return options.length + ' ' + this.nSelectedText + ' <b class="caret"></b>';
          }
          else {
            var selected = '';
            options.each(function() {
              var label = ($(this).attr('label') !== undefined) ? $(this).attr('label') : $(this).html();

              selected += label + ', ';
            });
            return selected.substr(0, selected.length - 2) + ' <b class="caret"></b>';
          }
        }
      }
    });
  });
</script>
numberDisplayed This option can be used to define the number of displayed option before the text defined in nSelectedText is used. This option may not be available when using a custom buttonText function. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      numberDisplayed: 4
    });
  });
</script>
buttonTitle Function defining the title of the button. Similar to the buttonText option. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      buttonTitle: function(options, select) {
        var selected = '';
        options.each(function () {
          selected += $(this).text() + ', ';
        });
        return selected.substr(0, selected.length - 2);
      },
    });
  });
</script>
buttonClass The class of the dropdown button. Default: btn. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      buttonClass: 'btn-primary btn-lg'
    });
  });
</script>
buttonWidth The width of the dropdown button. Default: auto. Allowed formats:
  • 100px
  • 50%
  • auto
If the width is defined using CSS the option should be set to false. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      buttonWidth: '300px'
    });
  });
</script>
buttonContainer The used container holding both the dropdown button and the dropdown menu. Default: <div class="btn-group" />. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      buttonContainer: '<span class="dropdown" />'
    });
  });
</script>
label Function to write the label of the item. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      label: function(element) {
      	return $(element).html()+' ('+$(element).val()+')';
      }
    });
  });
</script>
selectedClass The class applied to the parent <li> of selected items. Default: active. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      selectedClass: null
    });
  });
</script>
onChange This event handler is triggered when the selected options are changed. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      onChange: function(element, checked) {
      	alert('Change event invoked!');
      }
    });
  });
</script>
onDropdownShow This event handler is triggered when the dropdown are shown. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      onDropdownShow: function(event) {
      	alert('Show event invoked!');
      }
    });
  });
</script>
onDropdownHide This event handler is triggered when the dropdown are hidden. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      onDropdownHide: function(event) {
      	alert('Hide event invoked!');
      }
    });
  });
</script>
maxHeight Used for a long list of options this option defines the maximum height of the dropdown menu. If the size is exceeded a scrollbar will appear. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      maxHeight: 400
    });
  });
</script>
includeSelectAllOption If set to true a 'Select all' option will be added. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      includeSelectAllOption: true
    });
  });
</script>
selectAllText The label for the 'Select all' option. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      selectAllText: true
    });
  });
</script>
selectAllValue The value by which the select all option is identified. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      selectAllValue: 'multiselect-all',
    });
  });
</script>
enableFiltering If set to true a search field will be added to filter the visible options. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      enableFiltering: true
    });
  });
</script>
filterPlaceholder The placeholder used in the search field if filtering is enabled. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      filterPlaceholder: 'Search'
    });
  });
</script>
dropRight Will make the menu drop right if set to true. 
<script type="text/javascript">
  $(document).ready(function() {
    $('.multiselect').multiselect({
      dropRight: true
    });
  });
</script>

Methods

.multiselect('destroy')

This method is used to destroy the plugin on the given element - meaning unbinding the plugin.

.multiselect('refresh')

This method is used to refresh the checked checkboxes based on the currently selected options within the select. Click 'Select some options' so select some of the options (meaning added the selected attribute to some of the options). Then click refresh. The plugin will update the checkboxes accordingly.

.multiselect('rebuild')

Rebuilds the whole dropdown menu. All selected options will remain selected (if still existent!).

.multiselect('select', value)

Selects an option by its value. Works also using an array of values.

.multiselect('deselect', value)

Deselect an option by its value. Works also using an array of values.

.multiselect('dataprovider', data)

Provides data for building the select's options the following way: 

var data = [
    {label: "ACNP", value: "ACNP"},
    {label: "test", value: "test"}
];
$("#multiselect").multiselect('dataprovider', data);

.multiselect('setOptions', options)

Used to change configuration after initializing the multiselect. This may be useful in combination with .multiselect('rebuild').

.multiselect('disable')

Disable both the underlying select and the dropdown button.

.multiselect('enable')

Enable both the underlying select and the dropdown button.

Further Examples

Use "Select" and "Deselect" to select or deselectcheese and tomatoes. Use "Values" to display the currently selected elements by using $('.multiselect').val(). 

<script type="text/javascript">
  $('#example34').multiselect();
  
  $('#example34-select').on('click', function() {
    $('#example34').multiselect('select', 'cheese');
    $('#example34').multiselect('select', 'tomatoes');
  });

  $('#example34-deselect').on('click', function() {
    $('#example34').multiselect('deselect', 'cheese');
    $('#example34').multiselect('deselect', 'tomatoes');
  });

  $('#example34-values').on('click', function() {
    $('#example34-text').text('Selected: ' + $('#example34').val()).addClass('alert alert-info');
  });
</script>

Use the button to toggle the selection. 

<script type="text/javascript">
  /**
   * Gets whether all the options are selected
   * @param {jQuery} $el
   * @returns {bool}
   */
  function multiselect_selected($el) {
    var ret = true;
    $('option', $el).each(function(element) {
      if (!!!$(this).prop('selected')) {
        ret = false;
      }
    });
    return ret;
  }
   
  /**
   * Selects all the options
   * @param {jQuery} $el
   * @returns {undefined}
   */
  function multiselect_selectAll($el) {
    $('option', $el).each(function(element) {
      $el.multiselect('select', $(this).val());
    });
  }
  /**
   * Deselects all the options
   * @param {jQuery} $el
   * @returns {undefined}
   */
  function multiselect_deselectAll($el) {
    $('option', $el).each(function(element) {
      $el.multiselect('deselect', $(this).val());
    });
  }
   
  /**
   * Clears all the selected options
   * @param {jQuery} $el
   * @returns {undefined}
   */
  function multiselect_toggle($el, $btn) {
    if (multiselect_selected($el)) {
      multiselect_deselectAll($el);
      $btn.text("Select All");
    }
    else {
      multiselect_selectAll($el);
      $btn.text("Deselect All");
    }
  }
   
  $(document).ready(function() {
    $('#example21').multiselect();
    $("#example21-toggle").click(function(e) {
      e.preventDefault();
      multiselect_toggle($("#example21"), $(this));
    });
  });
</script>

When deselecting an option you will be asked for confirmation. 

<script type="text/javascript">
  $(document).ready(function() {
    $('#example22').multiselect({
      buttonClass: 'btn',
      buttonWidth: 'auto',
      buttonText: function(options) {
        if (options.length == 0) {
          return 'None selected <b class="caret"></b>';
        }
        else if (options.length > 6) {
          return options.length + ' selected  <b class="caret"></b>';
        }
        else {
          var selected = '';
          options.each(function() {
            selected += $(this).text() + ', ';
          });
          return selected.substr(0, selected.length -2) + ' <b class="caret"></b>';
        }
      },
      onChange: function(element, checked) {
        if(checked == true) {
          // action taken here if true
        }
        else if (checked == false) {
          if (confirm('Do you wish to deselect the element?')) {
            // action taken here
          }
          else {
            $("#example22").multiselect('select', element.val());
            return false;
          }
        }
      }
    });
  });
</script>

Switching between different configuration sets is possible using a combination of .multiselect('setOptions', options) and .multiselect('rebuild'). 

<script type="text/javascript">
  $(document).ready(function() {

    var firstConfigurationSet = {
      includeSelectAllOption: false,
      enableFiltering: false,
      enableCasInsensitiveFiltering: false
    };
    var secondConfigurationSet = {
      includeSelectAllOption: true,
      enableFiltering: true,
      enableCasInsensitiveFiltering: true
    };

    var set = 1;
    $('#example33').multiselect(firstConfigurationSet);
                    
    function rebuildMultiselect(options) {
      $('#example33').multiselect('setOptions', options);
      $('#example33').multiselect('rebuild');
    }

    $('#example33-configuration-set').on('click', function(event) {
      switch (set) {
        case 2:
          rebuildMultiselect(firstConfigurationSet);

          $(this).text('Configuration Set 2');
          set = 1;
          break;
        case 1:
        default:
          rebuildMultiselect(secondConfigurationSet);

          $(this).text('Configuration Set 1');
          set = 2;
          break;
      }
    });
  });
</script>

Limit the number of selected options using the onChange option. The user may only select a maximum of 4 options. Then all other options are disabled. 

<script type="text/javascript">
  $(document).ready(function() {
    $('#example37').multiselect({
      onChange: function(option, checked) {
        // Get selected options.
        var selectedOptions = $('#example37 option:selected');

        if (selectedOptions.length >= 4) {
          // Disable all other checkboxes.
          var nonSelectedOptions = $('#example37 option').filter(function() {
            return !$(this).is(':selected');
          });

          var dropdown = $('#example37').siblings('.multiselect-container');
          nonSelectedOptions.each(function() {
            var input = $('input[value="' + $(this).val() + '"]');
            input.prop('disabled', true);
            input.parent('li').addClass('disabled');
          });
        }
        else {
          // Enable all checkboxes.
          var dropdown = $('#example37').siblings('.multiselect-container');
          $('#example37 option').each(function() {
            var input = $('input[value="' + $(this).val() + '"]');
            input.prop('disabled', false);
            input.parent('li').addClass('disabled');
          });
        }
      }
    });
  });
</script>

Record the order the options are selected. When selecting an item an ordering number will be incremented and saved within the option 

<script type="text/javascript">
  $(document).ready(function() {
    var orderCount = 0;
    $('#example38').multiselect({
      onChange: function(option, checked) {
        if (checked) {
          orderCount++;
          $(option).data('order', orderCount);
        }
        else {
          $(option).data('order', '');
        }
      }
    });

    $('#example38-order').on('click', function() {
      var selected = [];
      $('#example38 option:selected').each(function() {
        selected.push([$(this).val(), $(this).data('order')]);
      });

      selected.sort(function(a, b) {
        return a[1] - b[1];
      });

      var text = '';
      for (var i = 0; i < selected.length; i++) {
        text += selected[i][0] + ', ';
      }
      text = text.substring(0, text.length - 2);

      alert(text);
    });
  });
</script>

Additional Styling

For additionaly styling of the multiselect button the CSS class multiselect can be used.

Text alignment combined with fixed width and bold, underlined text for option group headers. 

.multiselect {
  text-align: left;
}
.multiselect b.caret {
  position: absolute;
  top: 14px;
  right: 8px;
}
.multiselect-group {
  font-weight: bold;
  text-decoration: underline;
}

Access the select all option by using the .multiselect-all class. The filter search field can be manipulated by using .multiselect-search; 

.multiselect-all label {
  font-weight: bold;
}
.multiselect-search {
  color: red;
}

© 2012, 2013 David Stutz - dual licensed: Apache License v2.0, BSD 3-Clause License

JavaScript scaricato da HTML.it