jQuery MultiSelect

Written by Cory S.N. LaViska on April 6th, 2008

Improve multi-select form controls with this easy-to-use jQuery plugin.

Overview
Features
Compatibility
Demo
Download
Usage
To Do List
Licensing & Terms of Use

Overview

jQuery MultiSelect is a configurable plugin for jQuery. It is designed to turn ordinary multi-select form controls into user-friendly dropdown lists. Check out the demo to see an example.

This project was inspired by arco90’s MultiSelect tool, but was written entirely from scratch to make it easier to implement, more accessible, and to shorten the code length.

This project is in beta testing and may not be ready for production use yet! See the to do list for more information.

Features

Produces valid XHTML
Fully customizeable via CSS
Easy to configure and implement
Degrades gracefully
Keyboard shortcuts to maximize accessibility
Optional “Select All” for convenience

Compatibility

jQuery MultiSelect works in all browsers supported by jQuery. It has been fully tested in:

Internet Explorer 6 & 7
Firefox 2 & 3 (beta)
Safari 3
Opera 9

Demo

View a live demonstration of jQuery MultiSelect.

Download

Current version: Version 1.0 beta (05 April 2008)

Usage

Dependencies

jQuery MultiSelect requires jQuery 1.2 or above and the jQuery Dimensions plugin.

Creating

In it’s simplest form, you can create a MultiSelect form control using the following code:

$(document).ready( function() {

    $("#control_id").multiSelect();

});

where #control_id is the ID of the select element that exists on your page. You can use any valid jQuery selector as the ID, but make sure you only use select elements with the multiple="multiple" attribute to get the expected results.

Configuring

Parameters are passed as an object to the multiSelect() function. Valid options include:

Parameter	Description	Default Value
`selectAll`	whether or not to display the “Select All” option	`true`
`selectAllText`	text to display for selecting/unselecting all options simultaneously	`Select All`
`noneSelected`	text to display when there are no selected items in the list	`'Select options'`
`oneOrMoreSelected`	text to display when there are one or more selected items in the list (note: you can use % as a placeholder for the number of items selected). Use `*` to show a comma separated list of all selected items	`'% selected'`

To create a MultiSelect control with multiple parameters, your code will look something like this:

$(document).ready( function() {

    $("#control_id").multiSelect({

      selectAll: false,

      noneSelected: 'Check some boxes!',

      oneOrMoreSelected: '% options checked'

    });

});

Styling

The MultiSelect plugin relies 100% on CSS for styling. To give your users an aesthetically pleasing experience, you should either use the included stylesheet or create your own. Refer to jqueryMultiSelect.css to make any changes in the styles.

Callback

If you specify a callback function, the MultiSelect control will execute it whenever a checkbox’s checked state is changed. Currently, the function passes the checkbox element that was clicked as a jQuery object. To specify a callback function, your code will look something like this:

$(document).ready( function() {

    $("#control_id").multiSelect(options, function() {

        alert('Something was checked!');

    });

});

where options is either null or a JavaScript object (see configuring for details).

To Do List

As jQuery MultiSelect is still in beta testing, there is an actively-updated to do list. To add something to the list or to contribute to the project in any way, please contact me using our contact form. You will receive appropriate credit for any and all contributions you make to this project, however you must agree that all code you submit will fall under the same license as the jQuery MultiSelect project.

What’s Left?

Hide dropdown on a click that occurs outside of the dropdown/textbox
Remove textbox selection when focusing on textbox
“Select All” checkbox should be checked when all options get selected manually

Known Annoyances

When dropdown scrolls, keyboard shortcuts will not trigger scrollbar to follow selection

Known IE6 Differences

select layering bug (here is one possible solution that can be applied to your HTML/CSS)
Max-height doesn’s work (unsupported CSS property)
Clicking on labels won’t trigger the checkbox (normal browser behavior)

Licensing & Terms of Use

Comments

Slick stuff! My question: is there a way to list the items selected instead of 'x Selected' ie it would show 'Option 1 + Option 2 + Option 3 etc'...

#1 Jason on May 2nd, 2008

Have you seen this: http://lovcombo.extjs.eu ?

#2 Dezo on May 4th, 2008

Jason: there is now! Check out the demo to see it in action. Details on how to implement this feature are in the 'Configuring' section.

#3 Cory S.N. LaViska on May 5th, 2008

Is there a way to use this as a list box with the size="6"?

#4 Jon on May 22nd, 2008

css textboxt ınput (textfield) style - examples - -
http://www.css-lessons.ucoz.com/textbox-css-examples.htm

#5 chester on May 23rd, 2008

about css parameters...
http://css-lessons.ucoz.com/css-parameters.htm

#6 sezer on Jun 3rd, 2008

xxx

#7 xxxx on Jun 7th, 2008

Thanks for a great script, but please be aware that in the Multiple Parameters example above you haven't closed the document.ready function.

Cheers!

#8 Paul on Jun 16th, 2008

Thanks, Paul. Actually, I managed to forget to close out all of the examples. Fixed now :)

#9 Cory S.N. LaViska on Jun 16th, 2008

No problem! Seeing as you're clearly better at jquery than I am, any chance you could provide some help?

I'm trying to add an onclick event that takes the ID of the clicked <option> element and uses the jquery post method to obtain records from a database and returns html which will be placed into another element on the page.

However, as soon as I add the following code, the functionality of your script ceases to work. Any ideas?!

Any help would be MUCH appreciated!

$("#baselists").multiSelect(options,
function(){
$.post("final_list.php",
{ id: $(this).val(); },
function(data){
$("#final_list").html(data);
}
)
});

#10 Paul on Jun 17th, 2008

A very useful component!

I'm trying to do something similar to Paul, i.e. capturing the option that is selected/unselected and I had some problems that I could only resolve through changing the source of jqueryMultiselect.js.

When I created a multi selectbox using the following code:

$('.multiselect').multiSelect( null, function(el) {
alert("Option Clicked: " +el.value);
});

I would get 'Option Clicked: undefined' as the result. It seems as if an unknown object is being passed back. In order to fix this I changed the source of the multiselect method on lines 98, 172, 183 and 189 so the callback is passed 'this' rather than '$(this)'. By doing this the callback method is passed an HTMLInputObject and so the call to el.value returns correctly.

Is this the correct approach or is there a way to get at the selected option and interrogate it's properties?

#11 Andrew Dyer-Smith on Jul 5th, 2008

You have got a fantastic script. Thank you for the same, I have searched all over google and tried to crack into website but no use. Please tell what multi-select tools have these guys used on www.monstertemplates.com

#12 Natesh on Jul 14th, 2008

@Natesh: looks like it's a custom DIV that pops up when the "dropdown" is clicked. It's not very hard to do and you don't really need a plugin to do it.

#13 Cory S.N. LaViska on Jul 14th, 2008

First off, thanks very much - this was just what I was looking for. I've been playing with various dropdown/combobox/SELECT element plugins and hacks for days, but this one hits the nail on the head. I wasn't looking exclusively for multi-select capability, but I'll be using this to replace both standard single-select and multi-select form controls.

In case you're interested, I made some very small changes to the source to implement the following:

- exclusive (one-at-a-time) option selection
- passing of additional CSS classes for the INPUT and option DIV elements (order of precedence over multiSelect.css is naturally determined by the order the files are linked)

I found the additional CSS support very helpful in bringing the formatting in line with my existing form controls, and to make it easier to make global changes to all controls.

-----------

// New parameters:

/*

selectExclusive - only allow one item to be selected at a time; true/false, default = false

inputClass - name of css class to be applied to created INPUT element; this will be used in addition to the standard 'multiSelect' class (useful if you'd like to inherit existing formatting rather than modifying multiselect.css)

optionsClass - name of css class to be applied to created options DIV element; this will be used in addition to the standard 'multiSelectOptions' class

*/

// Added / changed code:

// line 40: added defaults
if( o.selectExclusive == undefined ) o.selectExclusive = false;
if( o.inputClass == undefined ) o.inputClass = '';
if( o.optionsClass == undefined ) o.optionsClass = '';

// line 44 & 45: changed to support override classes
var html = '<input type="text" readonly="readonly" class="multiSelect' + (o.inputClass ? ' ' + o.inputClass : '') + '" value="" style="cursor: default;" />';
html += '<div class="multiSelectOptions' + (o.inputClass ? ' ' + o.inputClass : '') + '" style="position: absolute; z-index: 99999; display: none;">';

// line 94: inserted support for selectExclusive on click event
if (o.selectExclusive){
$(this).parents('.multiSelectOptions').find('input:checked[value!=' + $(this).attr('value') + ']').attr('checked', false);
}

// line 185: inserted support for selectExclusive on Space and Enter keypress events
if (o.selectExclusive){
$(this).next('.multiSelectOptions').find('input:checked').attr('checked', false);
}

------------

Thanks again!

#14 Nathan Smith on Jul 16th, 2008

How to capture the data from control_7[] into a sendmail.php action script. The script does not read this at all.

But it works fine with control_3, control_4

#15 Natesh on Jul 28th, 2008

I have added a parameter iType to decide if the selectbox items are checkbox or radio.. Simply replaced all the checkbox references with the paramater and detected if it was a checkbox for the selectAll option (which should not be there if it is a radio list). Hope it makes sense

#16 Gary on Aug 22nd, 2008

Great plugin! I'm really glad to see this, the jQuery world needs a good multi-select plugin.

One thing I would suggest changing is the way you call the callback method.

Currently you do:
if( callback ) callback( $(this) );

I would suggest:
if( callback ) callback.apply( this , [this]);

This would make it parallel how jQuery does it's own internal callback methods and also follow a more traditional way for jQuery plugins to handle callbacks. The benefit is the context of the function, where with the way I propose you can access "this" and it refers to the DOM node being dealt with.

FWIW... I might also consider expanding the paramters, the example above only passes the element in, but you could also pass the select box as a second optional parameter as well.

Anyhow, tossing it out there... keep up the good work, and thanks for the great plugin!

Pax,
Stan

#17 Stan on Aug 22nd, 2008

I am new to jquery, How do i populate this dropdown with ajax return data

#18 rav on Aug 22nd, 2008

@rav: good question. This isn't built into the plug-in (yet?), so you'd really have to the code to get it to work.

Alternatively, you could create a SELECT element on the fly, populate it, and then run .multiSelect() on it. I'll have to think about that for feature enhancements.

@Stan: thanks for your insights. I'll definitely keep them in mind (as well as some other improvements) for the next version.

@Gary: thanks for the tip :)

#19 Cory S.N. LaViska on Aug 24th, 2008

Pretty cool script but can't make it work with ASP.NET / C#

When I apply it to my ASP DropDownList it works, shows up and everything.. but when I submit I only get the first selected item... I figured I'd try with a ListBox... same thing happens! and yes I set multiple=multiple on the dropdown and selectionmode=multiple on the listbox..

can't get the data :( Any help?

thx

A Beautiful Site

Search the Notebook

Popular Entries

Related Entries

Archives

Announcements