---

#Please, by advised that...

On March 4th 2013, this repository will change it's name for jquery.uix.multiselect to follow the same naming convention as my other jQuery UIx widgets. On that date, all forks will still point to this repository and will not be affected by this change, however any external references to it will have to be updated to maintain reliability. It is also recommended to rename your forks as well (but you don't have to... if you don't want to... I guess)

---

jQuery Multiselect

Version 2.0 RC

Introduction

This widget is a complete rewrite of the previous version. Why a new rewrite? Because the original widget's attempt was to create a all-in-one-out-of-the-box-multi-featured SELECT replacement and thus failed to be compliant with the DOMElement's behavior and limitations. Notably, it failed to :

• update the option items when modifying the SELECT element directly
• didn't support disabled items
• didn't support item groups
• etc.

Also, it quickly became slow when loading a few hundred items and some branches had drag and drop issues.

Release notes

This widget is stable enough to be used in staging environments. However it is still under development, in testing phase, as some features may require more feedbacks yet! (Mainly browser compatiblity.) At this point, expect minor bug fixes within 72 hours, and there will be no more features planned at this point.

Requirements

• jQuery 1.8+
• jQuery UI 1.9+

Features

• Support for disabled options
• Support for option groups
• Option group collapsable
• Draggable drop and/or sortable enabled
• Mouse selection mode (click, dblclick)
• Support for predefined or custom sort functions
• Searchable
• List layout and select direction (horizontal or vertical)
• Custom item renderer

Usage

Note : Even though it is a complete rewrite of the widget, I kept the multiselect widget name (but it is declared as uix.multiselect instead of ui.multiselect).

$('selector').multiselect();

To programmatically select/deselect, add/modify/remove items, you may access and modify the DOMElement directly, then call the refresh widget method to update it.

$('selector').append("<option value='item1'>My Item 1</option>")
             .multiselect('refresh');

// manually filter available options
//   This will only render visible the available items containing 'My Item' (case insensitive)
$('selector').multiselect('search', 'my item');

$('selector').multiselect('destroy');  // restore original element

See wiki documentation for more information.

TODO

• add custom item rendering support (needs more tests)
• Make all options as mutable as possible after initialization.
• Test in all major browsers (not fully tested)
• Mobile support
• Code cleanup
• etc.

Limitations

• When setting sortable option to true, options can only be reordered within their own groups. That is, an option cannot be reordered between two options of a different group. As this widget's purpose is not to extend the original element's behaviour beyound user interaction and presentation, this limitation shall not be lifted for the time being.
• This widget was designed for modern browsers usage. It is working fine in IE7+, Firefox and Chrome. Note that it will not work in quirks mode. There will be little to no support for non standards compliant browsers.