Yii 1.1: echmultiselect

Simple Wrapper Widget for the jQuery UI MultiSelect Widget by Eric Hynds

This is a simple Wrapper Widget for the jQuery UI MultiSelect Widget by Eric Hynds.


Tested with Yii 1.1.8.

Unpack the widget

Extract the contents of the zip file directly into the protected/extensions/ folder of your Yii application.

Use the widget

1. Basic Use with model and dropDownAttribute

Now you can use the widget in your view file, for example like this:

$data= CHtml::listData(Color::model()->findAll(), 'ID', 'Name');
$this->widget('ext.EchMultiSelect.EchMultiSelect', array(
    'model' => $model,
    'dropDownAttribute' => 'color',     
    'data' => $data,
    'dropDownHtmlOptions'=> array(

This Yii widget creates a 'drop down list' with the given data and applies the JQuery widget to it, which turns the ordinary HTML select control into an elegant MultiSelect list of checkboxes with themeroller support.

To avoid confusion: I refer to the initial select element (that is subsequently hidden) as the 'drop down list'; and to the eventual input element created by the JQuery Widget as the 'MultiSelect list'.

The provided 'dropDownHtmlOptions' will be adopted by the MultiSelect list. If you for example provide a style for the drop down list, it will also applied to the resulting MiltiSelect list.

The drop down list will be hidden directly after it is created: I placed a Javascript code to hide the element directly after it, to prevent it from being displayed while the page is loading, only to be hidden after the page has been loaded (as suggested here). I truly dislike that appearing/disappearing on page load, so I didn'd wait for the MultiSelect widget to hide the drop down list.

Note: You could also hide the drop down list by adding the style display:none to the dropDownHtmlOptions. But hiding it via JS-Code provides backward compatibility: if the user has JS disabled, multiselect will not work, but the original select element will stay visible.

2. Basic Use with name and value

$colors = array('red','yellow','orange','black','green','blue');
$this->widget('ext.EchMultiSelect.EchMultiSelect', array(
    'dropDownHtmlOptions'=> array(

Here, name is the name of the drop down list. This must be set if model and dropDownAttribute are not set. value contains the pre-selected input value(s). In this case, 'red' and 'yellow' will be pre-selected by default. value is used only if model is not set. If you select red, green, blue and submit, $_POST['colors'] will be an array containing the selected values, like: Array([0] => 0,[1] => 4, [2] => 5).

If model and dropDownAttribute are specified, they are used to generate the name and id of the drop down list. Note that if name is specified in addition, it overrides the automatically generated name. Similarly, if id is specified in the dropDownHtmlOptions, it overrides the generated id.

3. Use as a filter in CGridView

The following example was provided by jeremy (see comments)

$this->widget('zii.widgets.grid.CGridView', array(
    'columns' => array (
        // use EchMultiSelect for the next column
        array (
            'filter'=> $this->widget('ext.EchMultiSelect.EchMultiSelect', array(
                'model' => $model,
                'dropDownAttribute' => 'thirdColumn',
                'data' => $colors,
                'options' => array('buttonWidth' => 80, 'ajaxRefresh' => true),
            true // capture output; needed so the widget displays inside the grid

By setting 'ajaxRefresh'=>true, we indicate that the widget should be 'refreshed' after every ajax request that occurs on the current page.

Note that you have to change the original search criteria in the model file:

// $criteria->compare($alias.'.thirdColumn',$this->thirdColumn,true); // <-- original
// Now, that `$this->thirdColumn` is an array, you should use something like this:
if(!empty($this->thirdColumn)) {
    foreach($this->thirdColumn as $v) {
        $criteria->compare($alias.'.thirdColumnn', $v, false, 'OR');

Note: In your controller file where you render the grid, you should make the following changes if you have pre-selected values (thanks to Chris Backhouse for pointing out this issue):

public function actionAdmin()
    $model=new SomeModel('search');
    $model->unsetAttributes();  // clear any default values
    $model->thirdColumn = array('red','yellow'); // <-- pre-selected values.
    if(isset($_GET['SomeModel'])) {
            $model->thirdColumn = array(); // <-- clear pre-selected values

4. Overriding default options and filterOptions

You can provide optional parameters for the JQuery widget, if you want to change their default settings. Here's an example:

$data= CHtml::listData(Color::model()->findAll(), 'ID', 'Name');
$this->widget('ext.EchMultiSelect.EchMultiSelect', array(
    'model' => $model,
    'dropDownAttribute' => 'color',     
    'data' => $data,    
    'dropDownHtmlOptions'=> array(
    'options' => array( 
        'header'=> Yii::t('EchMultiSelect.EchMultiSelect','Choose an Option!'),
        'position'=>array('my'=>'left bottom', 'at'=>'left top'),
    'filterOptions'=> array(

Now the default “check all”, “uncheck all”, and “close” links in the header will be replaced with the specified text 'Choose an Option!, the widget will have a minimum width of 350px (instead of the default 225px), and the filter plugin will be applied.

Details about the available 'options' and 'filterOptions' for the jQuery UI MultiSelect Widget can be found on the Project page. Here's a list of the options and their default values for quick reference:

// 'options':
'header'=> true,
'checkAllText' => Yii::t('EchMultiSelect.EchMultiSelect','Check all'),
'uncheckAllText' => Yii::t('EchMultiSelect.EchMultiSelect','Uncheck all'),
'selectedText' =>Yii::t('EchMultiSelect.EchMultiSelect','# selected'),
'noneSelectedText'=>'-- ' . Yii::t('EchMultiSelect.EchMultiSelect','Select Options') . ' --',
// 'filterOptions':
'label' => Yii::t('EchMultiSelect.EchMultiSelect','Filter:'),
'placeholder'=>Yii::t('EchMultiSelect.EchMultiSelect','Enter keywords'),

The filter plugin is disabled by default. To enable it, you have to set the filter attribute to true. The filterOptions will have no effect, if filter is set to false, i.e. the filter plugin is disabled.

Note that the default options are already translated with Yii::t() where necessary.

For details about the position option see the jQuery page for the Position utility. The default position of the Multiselect list array('my'=>'left top', 'at'=>'left bottom').

5. import widgets in config file to simplify calls

As an alternative, you can import the path of your widgets in your config file protected/config/main.php:


Note that ext is short for application.extensions. Now you can call this widget (and any other widgets you may have placed under extensions/widgets/ ) with only its name, without specifying its path, i.e. like this:



  • Dec 17, 2012 (v1.3)
    • Added the changes suggested by jeremy in the comments, to make this widget work as a 'filter' in CGridView (added the ajaxRefresh and buttonWidth options). Thanks to jeremy for providing the code!
    • Added translation files. You can add your own translations to the folder EchMultiSelect/messages.
  • Mar 12, 2012 (v1.2)
    • Zipped the Widget-files directly, without putting them into an additional EchMultiSelect directory. That is: only directory structure changed. No changes in the code! (Reason of the change: The contents of the zip file are often extracted directly into the extensions directory, which resulted in the need to call the widget with $this->widget('ext.widgets.EchMultiSelect.EchMultiSelect', array(...);)
  • Feb 06, 2012 (v1.1)
    • Added the ability to pass options to the MultiSelect Filter Widget via parameter 'filterOptions' (thanks to sucotronic for pointing this out in the forum).
    • Made sure 'multiple' attribute of drop down list is set to 'true', even if not explicitly set in 'dropDownHtmlOptions' (only if 'multiple'=>true in 'options' of course).
    • Fixed a bug regarding the 'name' parameter


Total 20 comments

#18973 report it
chintan parikh at 2015/02/16 07:02am
dependent dropdown for echmultiselect

how to integrate dependent dropdown for this extension....?

#18959 report it
fsb at 2015/02/12 11:42am
Confusing error in 1st example under heading 3

there's a ) missing and the indentation is wicked confusing. try this instead: https://gist.github.com/tom--/0b80e18f08fe581e4402

#17511 report it
epulgaron at 2014/06/25 11:03am
I can not insert into the form

I have tried to use this extension, but I several problems arise One-not the dropdown closes when I choose an item 2-close button does not work me 3-when I give "insert" an element over my application throws me the error "field must be a number", the primary keys are integers and auto-increment

any idea?

this is my code

<div class="row">
        <?php echo $form->labelEx($model,'causas_cond_fk'); ?>
                $data= CHtml::listData(CausasCond::model()->findAll(array('order'=>'causas_cond_desc')),'id','causas_cond_desc');
                $this->widget('ext.EchMultiSelect.EchMultiSelect', array(
                'model' => $model,
                'dropDownAttribute' => 'causas_cond_fk',  (foreing key)   
                'data' => $data,
                'dropDownHtmlOptions'=> array(
                <?php echo $form->error($model,'causas_cond_fk'); ?>
#17080 report it
MarkBrass at 2014/04/30 02:17pm
Dropdown doesn't close

Once I open the list , I can't close it, not by clicking the select nor by the X button.

Any ideas why?

#16658 report it
pjravs at 2014/03/17 12:20am

I have a problem with this widget.

If I close it, it does not show up again. I have to refresh the page to select again. What seems to be the problem?

And also, is there an option that it shows the text that has been selected thanks!

#16275 report it
Peter NewbYii at 2014/02/05 05:08am
Multiselect + ListView + ajax GET + serialize form = request cache

Hi! I noticed, that when updated CListView via ajax like this:

$.fn.yiiListView.update('{your-clistview-id-here}', {
        data: $('.search-form form').serialize()

Select some options in your EchMultiSelect widget, then press search. You have GET request like this:

Model[attribute][] = 1
Model[attribute][] = 2
Model[attribute][] = 3

Then press clearAll button in your EchMultiSelect widget or manually unselect all the options and after that press search again - the request will be the same as the last one!

It looks like some cache. The {cache:false} option didn't resolve the issue.

So the only solution that I found was change request type from 'GET' to 'POST':

$.fn.yiiListView.update('{your-clistview-id-here}', {
data: $('.search-form form').serialize(),

Not sure what it is, but maybe it help anyone.

#16136 report it
c@cba at 2014/01/22 05:28pm
@Vinod Agarwal

Sorry for the (very) late reply, I was away for a while...
You probably already solved your problem, but for the sake of completeness:
I think the following should work

$columns[$i]['filter'] = $this->widget('ext.EchMultiSelect.EchMultiSelect', array(
    'dropDownHtmlOptions'=> array(
#15389 report it
Vinod Agarwal at 2013/11/05 12:45am
Add echmultiselect in filter dynamically

Hi , I have a CgridView in which columns are coming dynamically. So how to add this extension in filter. Currently I have filter in my column as :-

$columns[$i]['filter'] = CHtml::dropDownList($name, $model->$column_name,$options_value,array('multiple' => 'multiple', 'class' => 3));

#13980 report it
sucotronic at 2013/07/10 11:25am
Fix for yii 1.1.13

Download latest version of the following files in the assets folder:

  • https://raw.github.com/jquery/jquery-ui/master/ui/jquery.ui.widget.js (and rename to jquery.ui.widget.min.js)
  • https://raw.github.com/ehynds/jquery-ui-multiselect-widget/master/src/jquery.multiselect.js
  • https://github.com/ehynds/jquery-ui-multiselect-widget/blob/master/src/jquery.multiselect.filter.js
#13223 report it
senad87 at 2013/05/16 04:05am
Invalid alias

I was getting

Alias "ext.EchMultiSelect.EchMultiselect" is invalid. Make sure it points to an existing PHP file and the file is readable.

Just find out that there is a wrong alias in the examples.



and should be

------------------------------------------^ with capital S on last Select word

#12023 report it
jeremy at 2013/02/20 10:16pm
fixes to work with jQueryUI 1.9.2 (in Yii 1.1.13)

If you're having problems in Yii 1.1.13 (which includes jQueryUI 1.9.2), try this:
* upgrade assets/jquery.multiselect.js to multiselect v1.13
(from the author's site: http://www.erichynds.com/jquery/jquery-ui-multiselect-widget/)
* in assets/jquery.multiselect.js, make the following changes:
- in destroy(), comment-out
//$.Widget.prototype.destroy.call( this );
- in _setOption(), comment-out
//$.Widget.prototype._setOption.apply( this, arguments );

#11750 report it
arielon at 2013/02/01 06:20am
Some js errors found

If js errors, download the updated version of jquery.multiselect.js (http://www.erichynds.com/jquery/jquery-ui-multiselect-widget/)

#11737 report it
c@cba at 2013/01/30 02:46pm

@Sukhwinder: I really don't know what the problem could be and don't have the required system (debian+chrome) to test. It seems to be a compatiblity problem; maybe the jQuery plugin requires things that are not included in your system..?

@Chris Backhouse: Thanks for sharing the issue and its underlying reasons.

#11243 report it
Chris Backhouse at 2012/12/31 09:12am
Form submit inconsistencies

Hi, I'm just trying out your extension and have found that with the following scenario the wrong values are posted.

Form load, specify one entry of the list as pre-selected (eg: 'value'=>array(0) )

Post -> array OK

Click the previously selected entry (unselect)

POST -> same as first post, ie: previously selected entry is still selected. You would expect an empty array.

It looks as though this could be a problem with the jQuery plugin rather than your extension....any ideas?

UPDATE: When no options are selected it returns an empty string which is not returned by the jQuery(form).serialize() function. Therefore this is not passed onto any form submit. Subsequently it appears as though $.fn.yiiGridView.update must cache previous values and, as the multi-select variable is not defined, it is not getting re-initialised and the previous value is being POSTED to the controller action.

#11165 report it
Sukhwinder at 2012/12/21 02:16am
Drop down not closing

Hi i followed your instruction to use this extension, but facing following issues: 1. Old drop down list still showing on page 2. When i open Multi Select List, it opens, i can check/Uncheck, but it is not closing , i have to reload the page. 3. It is opening in black and white colors, no hover effect

PS Im using chrome, and my OS is Ubuntu 12.04


#11095 report it
c@cba at 2012/12/16 03:25pm
@jeremy - Thank You!!

Thank you so much for your contribution!! I wanted to do this myself for some time now, but didn't have the opportunity. I implemented your suggestion just now, it works perfectly.

Thanks again, this is very much appreciated! Do you mind if I incorporate this into the extension, with your comments?

#11094 report it
jeremy at 2012/12/16 09:15am
using EchMultiselect with CGridView

Here are the steps taken to make this very useful widget work as a 'filter' for CGridView.

The default behavior of CGridView is to do sorting/pagination/filtering in Ajax mode. After each ajax response, portions of the HTML response are used to update the grid. In this case the multi-select widget goes away and the default drop-down is displayed gain. To fix this, the caller should pass an additional option to indicate that it will be using ajax refresh, as follows:

  $options_default = array(
  'ajaxRefresh' => false, // add option to redisplay multiselect widgets after ajax refresh

at the end of run(), add the following logic:

  // for CGridView, <select> is refreshed on each ajax request, so the multiselect must be reapplied
  //   trigger this function to fire after ajax action is complete
  if ($this->options['ajaxRefresh']==true)
    $jscode .= "jQuery('body').ajaxComplete(function() {jQuery('#".$id."').multiselect(".$joptions."); });";
  Yii::app()->getClientScript()->registerScript(__CLASS__ . '#' . $id, $jscode);

Usage from within CGridView:

  'columns' => array (
    // use EchMultiselect for the next column
    array (
      'value'=> ...., 
      'filter'=> $this->widget('EchMultiselect',
          'model' => $model,
          'dropDownAttribute' => 'thirdColumn',
          'data' => ....
          'options' => array('buttonWidth' => 80, 'ajaxRefresh' => true),
      true // capture output; needed so the widget displays inside the grid

notice the new 'buttonWidth' option. This is because my Grid layout is extremely tight. I need the multi-select buttons to be as narrow as possible, but the drop-down menus to be wider (to show the full description). The default behavior does not support this.

implementation of 'buttonWidth' option in /assets/jquery.multiselect.js:

options: {
 buttonWidth: '', /*+ JJD */
  _setButtonWidth: function(){
    var width = this.element.outerWidth(),
      o = this.options;
    if( /\d/.test(o.minWidth) && width < o.minWidth){
      width = o.minWidth;
    // set widths
    /* JJD if buttonWidth set use it */
    if (o.buttonWidth)
      width = o.buttonWidth;
    this.button.width( width );
  // set menu width
  _setMenuWidth: function(){
    var m = this.menu,
        o = this.options, /* +JJD */
    width = this.button.outerWidth()-
     /* JJD if buttonWidth is manually set and minWidth is set and wider, use it */
     if (o.buttonWidth && o.minWidth && o.minWidth > o.buttonWidth)
       m.width( width || this.button.outerWidth() );  /* orig logic */
#11092 report it
jeremy at 2012/12/15 11:41pm
easier way to hide the default drop-down

instead of hiding the default drop-down with jQuery .hide(), I suggest:

init() {
 if (!isset($this->dropDownHtmlOptions['style']))
 $this->dropDownHtmlOptions['style'] .= ';display:none';
run() {
  // following line is not needed
  //echo '<script type="text/javascript">$("#'.$id.'").hide();</script>'; 
#10386 report it
deeptibaghel at 2012/10/24 03:12pm
In Multiselect mode, if there is a single option, it doesn't work

In Multiselect mode, if there is a single option, it doesn't work. The checkbox gets checked but it doesn't show "1 selected". Whereas it works with jquery ui demo at


Regards Deepti

#9116 report it
Vainglory07 at 2012/07/21 03:26pm

very nice widget:))

Leave a comment

Please to leave your comment.

Create extension