jQuery UI MultiSelect Widget ~ vZhai: Info Sharing Blog

jQuery UI MultiSelect Widget

This is the successor and port of my original jQuery MultiSelect Plugin to a jQuery UI widget. While both will actively be maintained, I highly recommend you use this version over the plugin version. It has a more robust feature set, is faster, and is much more flexible. MultiSelect turns an ordinary HTML select control into an elegant drop down list of checkboxes with themeroller support.
This version inherits all the benefits from the jQuery UI widget factory that are not available in the plugin version. The most requested feature was the ability to call methods on instances after initialization (e.g., statefullness), and now there are 10 to choose from! Also present are eight events you can bind to, which in the previous version, had fewer and limited support. Finally, there is support for effects. Just include the jQuery UI effects dependency and specify the name of the opening or closing effect to use (and speed, if you wish!)

Current version: 1.3 (07/08/2010 – changelog)
View demos
Download source or minified, and the CSS file.
Follow this project on GitHub
Run unit tests

Demo

See what you’re missing out on? Many more demos are available here.

The code behind this demo:

$("#multiselect-demo").multiselect({
show:"blind",
hide:"blind",
selectedText:"# of # selected"
});

Usage

Using this widget is simple. First, include the following files:

jQuery 1.4.2
jQuery UI 1.8 widget factory and effects (if you’d like to use them)
A jQuery UI theme
This widget: jquery.multiselect.js
The CSS file: jquery.multiselect.css

Next construct a standard multiple select box. If you want this widget to degrade gracefully when JavaScript is turned off, ensure the control has the multiple attribute:

<select id="example" name="example" multiple="multiple">
<option value="1">Option 1</option>
<option value="2">Option 2</option>
<option value="3">Option 3</option>
<option value="4">Option 4</option>
<option value="5">Option 5</option>
</select>

Finally, initialize the widget on the select box once the document is ready:

$(document).ready(function(){
$("#example").multiselect();
});

See the demos for advanced usages and for more documentation!

Options

To further customize multiselect, pass in a object with one or more of the options below.

// example:
$("select").multiselect({
header: "Choose an Option!"
});

Option	Description	Default
header	Either a boolean value denoting whether or not to display the header, or a string value. If you pass a string, the default “check all”, “uncheck all”, and “close” links will be replaced with the specified text.	true
height	Height of the checkbox container (scroll area) in pixels.	175
minWidth	Minimum width of the entire widget in pixels. Setting to “auto” will disable.	225
checkAllText	The text of the “check all” link.	Check all
uncheckAllText	The text of the “uncheck all” link.	Uncheck All
noneSelectedText	The default text the select box when no options have been selected.	Select options
selectedText	The text to display in the select box when options are selected (if `selectedList` is false). A pound sign (#) will automatically replaced by the number of checkboxes selected. If two pound signs are present in this parameter, the second will be replaced by the total number of checkboxes available. Example: "# of # checked". This parameter also accepts an anonymous function with three arguments: the number of checkboxes checked, the total number of checkboxes, and an array of the checked checkbox DOM elements. See examples for usage.	# selected
selectedList	A numeric (or boolean to disable) value denoting whether or not to display the checked opens in a list, and how many. A number greater than 0 denotes the maximum number of list items to display before switching over to the selectedText parameter. A value of 0 or false is disabled.	false
show	The name of the effect to use when the menu opens. To control the speed as well, pass in an array: `['slide', 500]`	empty string
hide	The name of the effect to use when the menu closes. To control the speed as well, pass in an array: `['explode', 500]`	empty string
autoOpen	A boolean value denoting whether or not to automatically open the menu when the widget is initialized.	false
multiple	If set to false, the widget will use radio buttons instead of checkboxes, forcing users to select only one option.	true

Events

Hook into any of the events below by either binding to the event name, or passing in the name of the event during initialization:

// bind to event
$("#multiselect").bind("multiselectopen", function(event, ui){
// event handler here
});

// or pass in the handler during initialization
$("#multiselect").multiselect({
open: function(event, ui){
// event handler here
}
});

Event	Description
beforeopen	Fires right before the menu opens. Prevent the menu from opening by returning false in the handler.
open	Fires after the widget opens.
beforeclose	Fires right before the menu closes. Prevent the menu from closing by returning false in the handler.
close	Fires after the widget closes.
checkAll	Fires when all the options are checked by either clicking the “check all” link in the header, or when the “checkall” method is programatically called (see next section).
uncheckAll	Fires when all the options are all unchecked by either clicking the “uncheck all” link in the header, or when the “uncheckall” method is programatically called (see next section).
optgroupToggle	Fires when an optgroup label is clicked on. This event receives the original event object as the first argument, and a hash of values as the second argument: $("#multiselect").bind("multiselectoptgrouptoggle", function(event, ui){ /* event: the original event object, most likely "click" ui.inputs: an array of the checkboxes (DOM elements) inside the optgroup ui.label: the text of the optgroup ui.checked: whether or not the checkboxes were checked or unchecked in the toggle (boolean) */ });
click	Fires when a checkbox is checked or unchecked. $("#multiselect").bind("multiselectclick", function(event, ui){ /* event: the original event object ui.value: value of the checkbox ui.text: text of the checkbox ui.checked: whether or not the input was checked or unchecked (boolean) */ });

Methods

After an instance has been initialized, interact with it by calling any of these methods:

// example:
$("#multiselect").multiselect("method_name");

Method	Description
open	Opens the menu.
close	Closes the menu.
update	Updates the current `selectedText`/`selectedList` value. Useful if you manually check/uncheck a box and need the widget’s text to reflect the changes.
disable	Disable the entire widget.
enable	Enable the entire widget.
checkall	Check all checkboxes.
uncheckall	Uncheck all checkboxes.
isOpen	Returns a boolean denoting if the widget is currently open or not.
getChecked	Returns an array of all the checked checkboxes.
widget	Returns the menu container (all checkboxes inside).
destroy	Destroy the widget, and revert back to the original select box.