filter-multi-select

Multiple select dropdown with filter jQuery plugin.

JSFiddle

Improve the useability of HTML <select> elements:

• options are displayed in a dropdown list.
• selected options are marked with a checkbox in the list and a badge at the top.
• easily select all or none.
• type to filter long lists of options.
• use the up/down arrow keys to focus an option and spacebar/enter to select.
• tab cycle to open/close dropdown.

Uses Bootstrap classes for styling. Easily modify CSS to match your theme.

Usage

1. Load jQuery, Bootstrap, and the plugin bundle in your HTML code.

   <script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
   <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"/>
   ...
   <link rel="stylesheet" href="filter_multi_select.css"/>
   <script src="filter-multi-select-bundle.min.js"></script>

2. Define a <select> element with name and multiple attributes in your HTML code. Supported optional attributes: disabled - disables the dropdown.
3. Define <option>'s with unique value attributes. Supported optional attributes: label - alternate dropdown display text; selected - pre-select this option; disabled - disable this option.

   <form>
     ...
     <select multiple id="pets" name="pets">
       <option value="0">Doge</option>
       <option value="1" selected>Keyboard Cat</option>
       <option value="2" label="Badger" disabled>Badger Badger Badger</option>
       ...

4. Use jQuery to target the <select> and apply the plugin. The HTML is replaced by the plugin in the DOM.

   <script>
     $(function () {
       $('#pets').filterMultiSelect();
     });
   </script>

5. Or append the class filter-multi-select to the select element and have it be targeted automatically.

   <select class="filter-multi-select" multiple id="pets" name="pets">



6. Listen to the events optionselected and optiondeselected to signal changes.

   <script>
     $(function () {
       $('#pets').on('optionselected', function(e) {
         ...
       });
     });
   </script>

Options

The following indexed parameters can be passed to filterMultiSelect() at construction.

• placeholderText - text to show as a placeholder when no items are selected. default="nothing selected"
• filterText - text to show in filter when empty. default="Filter"
• selectAllText - label for the select all dropdown item. default="Select All"
• labelText - label to display in the main dropdown. default=""
• selectionLimit - limit the number of items able to be selected. Choosing 1 or omitting the multiple attribute turns this into a single select. A value of 0 means no limit. default="0"
• caseSensitive - whether filtering is case-sensitive. default=false
• allowEnablingAndDisabling - whether programmatically toggling disabled is permitted. default=true
• items - array of additional items to append to options in dropdown. Each array entry should have the form:
  

  [label:string, value:string, selected?=false, disabled?=false]

API

The following methods are exposed on the plugin:

• hasOption(value:string) - returns true if this dropdown has an option with the specified value attribute, otherwise false.
• selectOption(value:string) - selects the option with the specified value attribute, otherwise does nothing if it does not exist or if it is disabled.
• deselectOption(value:string) - deselects the option with the specified value attribute, otherwise does nothing if it does not exist or if it is disabled.
• isOptionSelected(value:string) - returns true if the option with the specified value attribute exists and is selected, otherwise false.
• enableOption(value:string) - enables the option with the specified value attribute, otherwise does nothing if it does not exist or if enabling is not permitted.
• disableOption(value:string) - disables the option with the specified value attribute, otherwise does nothing if it does not exist or if disabling is not permitted.
• isOptionDisabled(value:string) - returns true if the option with the specified value attribute exists and is disabled, otherwise false.
• enable() - enables this dropdown, otherwise does nothing if enabling is not permitted.
• disable() - disables this dropdown, otherwise does nothing if disabling is not permitted.
• selectAll() - selects all non-disabled options.
• deselectAll() - deselects all non-disabled options.
• getSelectedOptionsAsJson(includeDisabled=true) - returns a JSON string of the selected options' values.

The following global fields are exposed on the jQuery extension point:

• $.fn.filterMultiSelect.selector - the selector string used to automatically target and apply the plugin. default = "select.filter-multi-select"
• $.fn.filterMultiSelect.applied - a collection of all element groups applied by the plugin.

The following data is available on the optionselected and optiondeselected event object e:

• e.detail.label - the display text of the option that was selected/deselected.
• e.detail.value - the value of the option that was selected/deselected.
• e.detail.name - the name of the select element from which the option was selected/deselected.