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.12 (11/26/2011 – changelog)
• View demos.
• Download source or minified, and the CSS file.
• Follow this project on GitHub.
• Run the unit tests.
• Please report any bugs on the issue tracker.

Demo

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

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

Advanced usage using optgroups and the filtering extension:

$("#multiselect-demo")
   .multiselect({
      noneSelectedText: 'Select car/boat manufacturers'
      selectedList: 4
   })
   .multiselectfilter();

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. Do not forget 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!"
});

/* button */
.ui-multiselect.myClass {}
 
/* menu */
.ui-multiselect-menu.myClass {}

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
	}
});

$("#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)
	*/
});

$("#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");

Filter Plugin

A filtering widget is available which, once initialized on a multiselect instance, will insert a text box inside the widget header. Typing in the input will filter rows and return matches in real time. To view a demo, download, or read the documentation, head to the demo page.

How do I…?

These questions came out of the comments which others will probably find useful:

Set default options for all multiselect instances?

$.ech.multiselect.prototype.options.selectedText = "# of # selected";

Retrieve all selected values?

var values = $("select").val();

var array_of_checked_values = $("select").multiselect("getChecked").map(function(){
   return this.value;	
}).get();

Retrieve values on the server?

Prevent the selectedList option from increasing the button’s height?

.ui-multiselect { height:25px; overflow-x:hidden; padding:2px 0 2px 4px; text-align:left }

Manually check or uncheck a checkbox?

// manually check (or uncheck) the third checkbox in the menu:
$("select").multiselect("widget").find(":checkbox").each(function(){
   this.click();
});

Show checked values on another part of my page?

Use multiselect in conjunction with the validate plugin?

Issues

If you find any issues, please report them using the GitHub issue tracker. Thanks!

Related posts:

1. jQuery MultiSelect Plugin w/ ThemeRoller Support
2. Using $.widget.bridge Outside of the Widget Factory
3. A jQuery UI Growl/Ubuntu-like Notification Widget

I’ve been working on a multiple select plugin on and off for the past couple months and finally have it stable enough for a first release. When I started this project my intentions were only to re-factor Cory LaViska’s MultiSelect implementation, but it quickly turned into a complete re-write with a focus on speed and ThemeRoller support. This plugin turns an ordinary HTML select control into an elegant drop down list of checkboxes.

• Current version: 0.6 (05/04/2010 – Changelog)
• View demos
• Download source (12.5 kb) or minified (6.8 kb), and the CSS file.
• Follow this project on GitHub

Features

• Full ThemeRoller support.
• Optgroup support with clickable labels.
• Optional header with check all / uncheck all / close links.
• Degrades gracefully.
• Keyboard support.
• Ability to hook into 5 different event callbacks.
• Display the checked options in a list with a configurable maximum.
• Easily change the position, fade speed, scroll container height, links text, and input text.
• The widget width inherits from the original element, but is also configurable as a parameter.
• Pre-selected & disabled option/widget support.
• bgiframe support.
• Only 6.9kb minified (2kb Gzipped).

Compatibility

MultiSelect is compatible with jQuery 1.4.0+ and all themes from jQuery UI 1.7+. This plugin is known to work in (but not limited to):

• Firefox 2 – 3.6
• IE 6 – 8
• Chrome Beta/4
• Safari 4
• Opera 10

Usage

First ensure you’ve included jQuery 1.4, a jQuery UI theme of your choice, and the jquery.multiselect.css file. You don’t need the jQuery UI library itself, just the theme files. The simplest use of MultiSelect is to bind the widget to your select box:

<select id="MySelectBox" multiple="multiple" name="MySelectBox">
<option value="1">Option 1</option>
<option value="2">Option 2</option>
</select>

$(document).ready(function(){
    $("#MySelectBox").multiSelect();
});

Do not forget to set your select boxes to multiple="multiple" if you want this plugin to degrade gracefully. Any option tags with the selected="selected" attribute will automatically be checked by default, and any option tags with the disabled="disabled" attribute will automatically be disabled by default.

Callbacks

Inside the onOpen callback, this refers to the container holding the header and checkboxes. If you want to gather all the checkboxes inside the multiselect that just opened, for example:

$("#MySelectBox").multiSelect({
	onOpen: function(){
		var $checkboxes = $(this).find('input');
	}
});

Inside the onClick callback, this refers to the checkbox that received the event. Example:

$("#MySelectBox").multiSelect({
	onClick: function(){
		if(this.checked){
			alert("I was just checked!");
		}
	}
});

See the options below for a full list of callbacks.

Overriding Options

Options for this plugin are exposed in $.fn.multiSelect.defaults, so you can override the default options for all instances like such:

// set the minWidth parameter for all instances to 500 pixels
$.fn.multiSelect.defaults.minWidth = 500;

Passing a function to the selectedText parameter

As of 0.5, the selectedText parameter can accept 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. As you can see in the example, this gives you 100% control of the display:

$("#MySelectBox").multiSelect({
	selectedText: function(numChecked, numTotal, checkedInputs){
 
		// example: emulating the default behavior
		return numChecked + " checked"; 
 
		// example: emulating the selectedList option
		return (numChecked < = 5) 
			? checkedInputs.map(function(element){ return element.title; }).join(', ')
			: numChecked + " checked";
	}
});

Options

This plugin is configurable with the following options:

Known Issues

A few issues are still outstanding:

• No onClose callback yet.
• The position should automatically change if the current position will prevent the options menu from showing. E.g., if the input is at the bottom of the page, the options should appear not appear below the input.
• In IE, the shadow parameter increases the width and height of the container, rendering it a few pixels wider than the input and throwing off the alignment. You can easily edit the CSS file and remove the IE-specific shadow filters, however, or opt not to use it.
• If the select box you’re transforming into a multiselect is disabled, the option tags will actually inherit the disabled property only in webkit; Firefox and IE do not display this behavior. I’ve filed a bug on this. Therefore, to be cross-browser compatible, if the entire widget is disabled by default, the class ui-state-disabled is applied and the disabled attribute is removed. This is important to note because checkbox values could be transmitted during submit, even if the select is disabled. To toggle disabled state, toggle the ui-state-disabled class on the widget.

  This bug does NOT effect the disabled state of specific option tags.

Related posts:

1. jQuery UI MultiSelect Widget
2. jQuery Related (Dependent) Selects Plugin