Skip to content

Multiple select dropdown with filter jQuery plugin.

License

Notifications You must be signed in to change notification settings

andreww1011/filter-multi-select

Repository files navigation

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.