how to customize template for checkboxlist

I have been trying to customize checkboxlist template, but it did not work. Below is the code to display checkboxlist

<?php echo $form->field($model, 'category_id')->checkboxList(




            ), [

            'item' =>

                function ($index, $label, $name, $checked, $value) {

                    return Html::checkbox($name, $checked, [

                        'value' => $value,

                        'label' => '<label for="' . $label . '">' . $label . '</label>',

                        'labelOptions' => [

                            'class' => 'ckbox ckbox-primary col-md-4',


                        //'id' => $label,




            'separator'=>false,'template'=>'<div class="item">{input}{label}</div>',]);


Please anyone can tell me where is the problem. I have applied same solution on yii2 documentation.

Please help me to customize

"item" should be "items"

Thanks for your reply,

I have changed "item" to "items", it giving me warning

htmlspecialchars() expects parameter 1 to be string, object given

What if I remove whole item array and add template. How can I set template for that.

According with the documentation, you should give an array for "items", you are using a function instead.

Anyway maybe you can find some usefull tips here:

and also reading this official document:

If you want to create a template you can change the form options

Or you can extend the baseHtml Class

Otherwise, if you need to make some change dinamicaly on client side, you can use jquery.

As you can see the code, there is an item array that I removed. Checkbox list is displayed. But template text is added into parent div like

<div id="websitebusinesscategory-category_id" template="<div class=&quot;item&quot;>{input}{label}</div>">

So I think there is no issue with code. But some convention is missing or I am missing something. But What I don’t know.

Ok reading at your code, there are some errors.

You should modify like this


      $form->field($model, 'category_id')


                            'items' = [ArrayWithYourValues], 

                            'options' = [

                                    'tag'=>Your html container,

                                    'item'=>function ($index, $label, $name, $checked, $value){

                                            //Your custom html code for each element





Sorry but I am working i didn’t read carefully your code :o

As per your code, it did not work for me. I am still stuck at this place. Please anybody have any solution…

Maybe with this example is clearer


$form->field($model, 'category_id')




                         'item'=>function ($index, $label, $name, $checked, $value){

                            return '<div class="col-md-12">

                                         <input type="checkbox" />'.$label.'






The above answers are close here is a working and tested version.


 $form->field($model, 'category_id')->checkboxList(\yii\helpers\ArrayHelper::map(common\models\BusinessCategory::find()->all(), "id", "name"), [

        	'onclick' => "$(this).val( $('input:checkbox:checked').val()); ",//if you use required as a validation rule you will need this for the time being until a fix is in place by yii2

        	'item' => function($index, $label, $name, $checked, $value) {

            	return "<label class='ckbox ckbox-primary col-md-4'><input type='checkbox' {$checked} name='{$name}' value='{$value}' tabindex='3'>{$label}</label>";




The above are missing checked and the label. Without the label wrapping it and not setting any attributes it will only allow for the checkbox to be checked by clicking the box. This way will still result in default behavior of clicking the box or the label to check it. Without the checked var being used you will not be able to set a checked value in the controller if need be as well.

The above will work for radio list as well. You will have to change change type=checkbox to type=radio and make it use yii2’s radio list instead of checkbox list.

That’s perfect. Thank you so much @Grischer and @skworden for your valuable reply. I got it working perfectly.

I want to add another feature in checkboxlist. I have categories table and category may have child categories. So How can I create checkboxlist like tree structure for this categories.

Do I need to create separate issue or It is okay?

Glad you got it working. You will have to use a different widget that can support the the category sub-tree. Here is one

Fancy tree

Here are some examples

If you need help with it I’d start a new post.

Thank you. I am creating new post for this…