# 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.

# 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 add the `multiple="multiple"` attribute automatically. The first option is selected automatically by the browser when ommitting the `multiple` attribute. But note: If the `mutliple` attribute is omitted and more than one option is selected by default, the browser will select the last selected option before the plugin has the chance to add the `mutliple` attribute.
| Select with preselected options: `<option value="cheese" selected>Cheese</option>`
| As link using `buttonClass: 'btn btn-link'`.
| Small button using `buttonClass: 'btn btn-small'`.
| Disabled using `buttonClass: 'btn btn-primary disabled'`.
| Multiple select within a group with add-ons and default container for the plugin: `buttonContainer: '<div class="btn-group" />'`.
| Multiple selects within a group using `buttonContainer: '<span class="dropdown" />'`.
| 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>`

# Code

Basic markup used in the above examples:

    <link rel="stylesheet" href="css/bootstrap.min.css" type="text/css">
    <link rel="stylesheet" href="css/bootstrap-responsive.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>
    <script type="text/javascript" src="js/bootstrap-multiselect.js"></script>

    <script type="text/javascript">
      $(document).ready(function() {
        $('.multiselect').multiselect({
          buttonClass: 'btn',
          buttonWidth: 'auto',
          buttonContainer: '<div class="btn-group" />',
          maxHeight: false,
          buttonText: function(options) {
            if (options.length == 0) {
              return 'None selected <b class="caret"></b>';
            }
            else if (options.length > 3) {
              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>';
            }
          }
        });
      });
    </script>

    <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>

    <div class="input-prepend input-append">
      <span class="add-on"><b class="icon-list-alt"></b></span>
      <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>
      <button class="btn btn-danger">Cancel</button>
      <button class="btn btn-success">Save</button>
    </div>

# 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.
`.multiselect('deselect', value)` |  | Deselect an option by its value.

# Further Examples

    <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).attr('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());
    		});
    		console.log($('option[selected]', $el).length)
    	}
    	/**
    	 * Deselects all the options
    	 * @param {jQuery} $el
    	 * @returns {undefined}
    	 */
    	function multiselect_deselectAll($el) {
    		$('option', $el).each(function(element) {
    			$el.multiselect('deselect', $(this).val());
    		});
    		console.log($('option[selected]', $el).length)
    	}

    	/**
    	 * 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({
    			buttonContainer: '<span />'
    		});
    		$("#example21-toggle").click(function(e) {
    			e.preventDefault();
    			multiselect_toggle($("#example21"), $(this));
    		});
    	});
    </script>
    <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>

# 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 'None selected <b class="caret"></b>';
            }
            else if (options.length > 3) {
              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>';
            }
          }
        });
      });
    </script>
`buttonClass` | The class of the dropdown button. Default: `btn`. |
    <script type="text/javascript">
      $(document).ready(function() {
        $('.multiselect').multiselect({
          buttonClass: 'btn-primary btn-large',
        });
      });
    </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>
`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>
`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>

# 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 {
    	float: right;
    }
    .multiselect-group {
    	font-weight: bold;
    	text-decoration: underline;
    }

© 2012 David Stutz - Apache License v2.0