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