jQuery MultiSelect

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

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

Contents

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

Compatibility

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

Demo

View a live demonstration of jQuery MultiSelect.

Download

Current version: Version 1.0 beta (05 April 2008)

This plugin is provided to you as-is, at absolutely no cost. If you would like to support its development, feel free to contribute any amount you prefer via PayPal. As always, you are welcome to contribute code for bug fixes and feature enhancements as well. Either way, thanks for supporting our efforts!

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:

ParameterDescriptionDefault Value
selectAllwhether or not to display the “Select All” optiontrue
selectAllTexttext to display for selecting/unselecting all options simultaneouslySelect All
noneSelectedtext to display when there are no selected items in the list'Select options'
oneOrMoreSelectedtext 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?

Known Annoyances

Known IE6 Differences

Licensing & Terms of Use

jQuery MultiSelect is licensed under a Creative Commons License and is copyrighted ©2008 by Cory S.N. LaViska.

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

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!

#7 Paul on Jun 16th, 2008

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

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

#9 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?

#10 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

#11 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.

#12 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!

#13 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

#14 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

#15 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

#16 Stan on Aug 22nd, 2008

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

#17 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 :)

#18 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

#19 Mike on Aug 27th, 2008

Excellent plugin - It is really great for our complex searches.

One problem that our users have is that it sometimes fails to collapse. If you drop down the options, hover over the options and then move the mouse out of the control by passing it across the input box, it does not collapse. Our uses got frustrated when a click elsewhere on the page did not collapse the box.

I hacked it with this code. I do not have any other document level click handlers, so I can safely unbind them all. Your mileage may vary.


// Hide the dropdown
multiSelectOptionsHide: function() {
$(this).removeClass('active').next('.multiSelectOptions').hide();
$(document).unbind('click');
},

// Show the dropdown
multiSelectOptionsShow: function() {
// Hide any open option boxes
....
$(document).click( function(ev) {
// If the click is within the option list, only one extended, so ignore
var container = $(ev.originalTarget).parents('.multiSelectOptions');
if (container.length == 0) {
$(multiSelectCurrent).multiSelectOptionsHide();
$(multiSelectCurrent).unbind("hover");
}
});
},


#20 Kevin on Sep 18th, 2008

The above problem and solution are firefox specific.

#21 Kevin on Sep 18th, 2008

Great plugin, looking forward to the next version.

I had a problem with the placement of the div that drops down, the position it got was calculated from the left and top of the document, while the absolute positioning positioned it with those values from the containing div.

I solved it by adding a 'containingDiv' parameter, and where it set the positioning on the div i also fetched the position of the containing div and subtracted its values from the position values of the drop down div and it works.

#22 Fredrik on Sep 25th, 2008

I don't believe dimensions is needed anymore as it's built into jquery. Why and...

var offset = $(this).offset();

needs to be changed to:

var offset = $(this).position();

#23 James on Oct 3rd, 2008

Hi,

Would this be very easy to use as a list box instead of a combo box. I love the functionality but I need it to stay up all the time so that the options are always visible.?

I'm a very inexperienced coder so apologies if it's an obvious question.

#24 Ben on Oct 11th, 2008

Hi,

Thanks for the multi select plug-in.
Could you please help me to get the selected values from the multi select options list?

I have added a button in my form and I need to find out the selected options when I click the button.

I tried with call back that seems to respond for every click. I need to get the selected values once even if the user did not explicitly selected an option (need to get the default values).


$('#MultipleOptions').multiSelect( null, function(el) {
alert("Option Clicked: " +el.val());
});

Thanks in advance for your help.

#25 Cynthi on Oct 31st, 2008

Another nice script! You're doing some great stuff over here!

#26 Webdesign Meppel on Nov 3rd, 2008

Hi, I have a e-trade project.

I use this script ? This free ?

Thanks.

#27 samet on Nov 5th, 2008

Hi,

First of all thanks for this greatly useful component.

I have a request for feature:
If one of the options is disabled by default(by doing disabled="disabled") then the checkbox should also render disabled by default and "Select All" should not check it.

Currently it doesn't do this.

Thanks

#28 Rachit on Nov 5th, 2008

@samet: Please refer to the licensing section to answer your question.

#29 Cory S.N. LaViska on Nov 5th, 2008

Thanks, but ı don't just understand .

Because, ı don't good understand english. ( and licensing text very long )

#30 samet on Nov 5th, 2008

I'd like to see an answer to Cynthia's question, because I too am baffled. How do you get the selected values out of the control?

#31 Steve on Nov 5th, 2008

@Cynthi & Steve: see the demo for how to retrieve the selected values. When placed in a form, it will submit the same way as it would if it were just a SELECT element. That said, you can use $.serialize() or simply check the value using document.getElementById.

#32 Cory S.N. LaViska on Nov 5th, 2008

example:

<option value="1">One</option>
<option value="2">Two</option>
<option value="3">There</option>
<option value="4">Four</option>
<option value="5">Five</option>
<option value="6">Six</option>
**

I selected One,Three,Five and Four.

Output : /1/Three/5/4

sometimes,

output: /One/3/Five/4


I one by one choosing box , sometimes corrupt output. But I checked "select all" everything normal.

its time output : /1/3/5/4

Cause ? :S

#33 samet on Nov 7th, 2008

Hello,
Thank you for your nice pluggin.
Nevertheless I've notice that if the <select> is in a div with "position:fixed" attribute, the droplist is not displayed.
I've not managed to found a solution ... does a solution exist ?
Thanks
NLA

#34 nla on Nov 12th, 2008

pretty control by works slowly on large amount of data due to the fact the author does not use direct addressing of html elements of the control. This approach increases a cost of a support of the control as well.

#35 JOhn on Dec 8th, 2008

If you use <label for="x">CHB</label><input type="checkbox" id="x" ... /> then the label clicks will trigger the checkbox. I hope it helps.

#36 Caner on Dec 8th, 2008

Good but don't work with any form-styler like jform. Like Nathan, I add input id support.

#37 ben on Dec 10th, 2008

Hi,

I'm using this plugin with worpress, but the effect only works in the home page.
Any ideas ?
Thanks
www.kalyrock.com

#38 ado on Dec 13th, 2008

Nathan's Class and selectExclusive + Id and Pagination, skinnable, would be great to have a good and usable release.

#39 ben on Dec 18th, 2008

I would like to suggest a feature to initialize without checked options, I modify the plugin commenting the line 50 to get this behavior.

'//if( $(this).attr('selected') ) html += ' checked="checked"';'

Good plugin!

#40 Felipe on Dec 24th, 2008

Hi all,

I use it on Asp.net DropDownList control, but found "AutoPostBack" failed.

The same thing happen on javascript onChange() event.

Can anyone help?

By the way, it's really a good plugin.


#41 derek on Dec 30th, 2008

Hi,

Thanks for a great Plugin...
Instead of using checkbox can i make use of textbox if so how do i get sum of values of text box's within a select

#42 Mahesh on Jan 2nd, 2009

Further to the above question, How to evaluate onchange of select

#43 Mahesh Dasari on Jan 5th, 2009

Add a comment

Name*

Email*

Never, ever sold or spammed :)

Homepage

Comment*

Sorry, plain text only :(