Yii 2 CheckboxX

Latest Stable Version Latest Unstable Version Total Downloads Monthly Downloads Daily Downloads
Thankful to Krajee!
to get more out of us.

NOTE: This extension depends on the kartik-v/yii2-krajee-base extension which in turn depends on the yiisoft/yii2-bootstrap extension. Check the composer.json for this extension's requirements and dependencies that may be updated by composer.

An extended checkbox widget for Yii Framework 2 based on the bootstrap-checkbox-x jQuery plugin by Krajee. This widget allows three checkbox states and includes additional styles. The plugin uses Bootstrap markup, glyphs, and CSS 3 styling by default, but it can be overridden with any other markup.

Note

The checkbox plugin stores the values as integer format (and not boolean format) for checked and unchecked states.

The checkbox-x input offers these advanced features:

  • The plugin offers the following three states and values for the checkboxes:

    • 1: Checkbox is checked.

    • 0: Checkbox is unchecked.

    • null: Checkbox is indeterminate.

  • You can set the plugin to allow three states or the default two states for the checkbox.

  • Specifically uses Bootstrap 3.x styles & glyphs. One can configure the checked, unchecked, and indeterminate icons to be shown for the checkboxes.

  • Special CSS 3 styling, to enhance the control to look like any Bootstrap 3 form control. Supports the has-error, has-success, has-warning styling states like other Bootstrap form-controls.

  • Plugin CSS styling automatically defaults the checkboxes to inline display. You can also control the markup for block display like in checkbox lists.

  • You can add a label before or after with a for attribute and click on the label to change the checkbox values. Alternatively you can enclose the input within a label tag as well.

  • Ability to navigate to the checkbox controls via keyboard, and modify the values using the space bar on the keyboard.

  • Ability to size the checkbox control. Five prebuilt size templates are available xl, lg, md, sm, and xs.

  • Triggers JQuery events for advanced development. The plugin automatically triggers the change event for the input, whenever the checkbox value is changed via clicking. Events currently available are change and reset.

  • Ability to access methods and refresh the input dynamically via javascript at runtime.

  • Disabled and readonly checkbox input support.

  • Size of the entire plugin (JS and CSS) is less than 2KB when minified and gzipped. Its about 6KB when minified without gzipping (about 3KB for the JS and 3KB for the CSS).

The preferred way to install this extension is through composer.

Note

You must read this web tip / wiki on setting the minimum-stability settings for your application's composer.json.

Either run:

$ php composer.phar require kartik-v/yii2-checkbox-x "*"

or add:

"kartik-v/yii2-checkbox-x": "*"

to the require section of your composer.json file. Then run:

php composer.phar update

to get the updated package on your application install.

Note

The CheckboxX widget reads and returns the value as integers and not boolean. The following values are parsed and returned:
  • 1 for checked state

  • 0 for unchecked state

  • null for indeterminate state

The CheckboxX widget supports all parameters that one would pass for any Yii Input Widget. The additional parameter settings specially available for the CheckboxX widget configuration are:

  • initInputType: string the input type used for initializing the widget. This can be one of CheckboxX::INPUT_TEXT or CheckboxX::INPUT_CHECKBOX. Defaults to CheckboxX::INPUT_TEXT. Note, the widget by default uses a text input to initialize the plugin instead of checkbox for better label styling, alignment and using templates within ActiveField.

  • autoLabel: boolean automatically generate, style, and position labels with respect to the checkbox x. Defaults to false. If this is true, the labels will automatically be positioned and styled based on label settings. When this is set to true and you have set the model and attribute, the label will be automatically generated. If you are not using this with a model, then you must set the property labelSettings['label'] for automatic label styling to work. NOTE If this is true, and you are using the widget within yii ActiveField, then you must disable the active field label generation to avoid duplicate labels. For example:

    echo $form->field($model, 'attr')->widget(CheckboxX::classname(), [
        'autoLabel'=>true
    ])->label(false);
    
  • labelSettings: array the settings for the label. The following properties are recognized:

    • label: string, the label to be used. When using with model, this will be automatically generated if not set.

    • position: string, the position of the label with respect to the checkbox. Must be one of CheckboxX::LABEL_LEFT or CheckboxX::LABEL_RIGHT. Defaults to CheckboxX::LABEL_RIGHT if not set.

    • options: array, the HTML attributes for the label.

  • disabled: boolean whether the input widget is to be entirely disabled. Defaults to false.

  • readonly: boolean whether the input widget is to be entirely readonly. Defaults to false.

  • options: array the HTML attributes for the widget input tag.

  • pluginLoading: boolean, whether to show a loading progress indicator in place of the input before plugin is completely loaded. Defaults to true.

  • pluginOptions: array the plugin settings/options for the Bootstrap Checkbox X Plugin. There are a quite a few options you can set in this plugin. Refer the plugin options documentation for details.

  • pluginEvents: array the StarRating JQuery events. You must define events in event-name=>event-function format. All events will be stacked in the sequence. Refer the plugin events documentation for details. For example:

    pluginEvents = [
        "change"=>"function() { log("change"); }",
        "reset"=>"function() { log("reset"); }",
    ];
    



Basic Checkbox X with ActiveForm. Check the model validation, when you set the value to null. You can also navigate using keyboard navigation keys and use the space bar key to modify.


Allow only 2 states for the checkbox. Add your own label markup for the checkbox (which can be clicked to set the value).



Inline label alignment options - left, right, or enclosed. Also note checkbox with initial values.

Control checkbox sizes.

Disabled and readonly checkboxes

Block style checkboxes like in checkbox list. Customize indicators for checked, unchecked, and indeterminate states.



Advanced label styling and positioning when using with Yii ActiveForm & ActiveField. Shows how you can right align labels by changing the template property of ActiveField. You can also control the HTML attributes for the label via labelOptions.
use kartik\checkbox\CheckboxX;
use kartik\widgets\ActiveForm;
$form = ActiveForm::begin();

// Basic Checkbox X with ActiveForm. Check the model validation, when you set the value to null. 
// You can also navigate using keyboard navigation keys and use the `space bar` key to modify.
echo $form->field($model, 'status')->widget(CheckboxX::classname(), []); 

// Allow only 2 states for the checkbox. Add your own label markup for the checkbox (which can be clicked to set the value).
echo '<label class="cbx-label" for="s_1">Is Active?</label>';
echo CheckboxX::widget([
    'name'=>'s_1',
    'options'=>['id'=>'s_1'],
    'pluginOptions'=>['threeState'=>false]
]);

//  Inline label alignment options - left, right, or enclosed. Also note checkbox with initial values.
echo '<label class="cbx-label" for="s_2">Left</label>';
echo CheckboxX::widget([
    'name'=>'s_2',
    'value'=>1,
    'options'=>['id'=>'s_2']
]);
<span style="border-left: 1px solid #ddd; margin:0 15px 0 11px;"></span>
echo CheckboxX::widget([
    'name'=>'s_3',
    'value'=>0,
    'options'=>['id'=>'s_3']
]);
echo '<label class="cbx-label" for="s_3">Right</label>';
<span style="border-left: 1px solid #ddd; margin:0 15px 0 11px;"></span>
echo '<label class="cbx-label" for="s_4">
    Enclosed
    echo CheckboxX::widget([
        'name'=>'s_4',
        'options'=>['id'=>'s_4']
    ]);
</label>';

// Control checkbox sizes.
echo CheckboxX::widget(['name'=>'s_5', 'options'=>['id'=>'s_5'], 'pluginOptions'=>['size'=>'xs']]); 
echo '<label class="cbx-label" for="s_5">xs</label>';
echo CheckboxX::widget(['name'=>'s_6', 'options'=>['id'=>'s_6'], 'pluginOptions'=>['size'=>'sm']]); 
echo '<label class="cbx-label" for="s_6">sm</label>';
echo CheckboxX::widget(['name'=>'s_7', 'options'=>['id'=>'s_7'], 'pluginOptions'=>['size'=>'md']]); 
echo '<label class="cbx-label" for="s_7">md</label>';
echo CheckboxX::widget(['name'=>'s_8', 'options'=>['id'=>'s_8'], 'pluginOptions'=>['size'=>'lg']]); 
echo '<label class="cbx-label" for="s_8">lg</label>';
echo CheckboxX::widget(['name'=>'s_9', 'options'=>['id'=>'s_9'], 'pluginOptions'=>['size'=>'xl']]); 
echo '<label class="cbx-label" for="s_9">xl</label>';

// Disabled and readonly checkboxes
echo CheckboxX::widget([
    'name'=>'s_10', 
    'value'=>1,
    'disabled'=>true,
    'options'=>['id'=>'s_10'], 
]); 
echo '<label class="cbx-label" for="s_5" class="text-muted">Disabled</label>';
echo CheckboxX::widget([
    'name'=>'s_11',
    'readonly'=>true, 
    'options'=>['id'=>'s_11'], 
]);>
echo '<label class="cbx-label" for="s_11" class="text-muted">Readonly</label>';
 
// Block style checkboxes like in checkbox list. Customize indicators for checked, 
// unchecked, and indeterminate states.
<?php $pluginOptions = [
    'inline'=>false, 
    'iconChecked'=>'<i class="glyphicon glyphicon-plus"></i>',
    'iconUnchecked'=>'<i class="glyphicon glyphicon-minus"></i>',
    'iconNull'=>'<i class="glyphicon glyphicon-remove"></i>'
];
echo CheckboxX::widget([
    'name'=>'s_12', 
    'value'=>1,
    'pluginOptions'=>$pluginOptions
]);
echo CheckboxX::widget([
    'name'=>'s_13', 
    'value'=>0,
    'pluginOptions'=>$pluginOptions
]);
echo CheckboxX::widget([
    'name'=>'s_14',
    'pluginOptions'=>$pluginOptions
]);

// Advanced label styling and positioning when using with Yii ActiveForm & ActiveField. 
// Shows how you can right align labels by changing the template property of ActiveField. 
// You can also control the HTML attributes for the label via `labelOptions`.
echo $form->field($model, 'rememberMe', [
    'template' => '{input}{label}{error}{hint}',
    'labelOptions' => ['class' => 'cbx-label']
])->widget(CheckboxX::classname(), ['autoLabel'=>false]);
ActiveForm::end();



Initialize using a checkbox input and when using with ActiveForm & ActiveField. Enable autoLabel property to auto style and position your labels, and disable the default label of ActiveField (using label(false) method).

 
Initialize using a checkbox input. Along with autoLabel enabled configure the labelSettings to set your own labels, styles and position them to left and right.

 
Auto style disabled and readonly labels.

Use customized HTML markup as checkbox indicators. Also set your own advanced label styles.

Use native checkboxes with enabled tri state behavior and enclosed label.

Krajee Flat Blue Theme
Default Theme

Theming support. Use alternative Krajee Flat Blue theme by setting theme to krajee-flatblue within pluginOptions.

To add your own theme - create your CSS using container CSS class based on cbx-{NAME} where {NAME} is the theme set in pluginOptions['theme'].

use kartik\checkbox\CheckboxX;
use kartik\widgets\ActiveForm;
$form = ActiveForm::begin();
// Initialize using a checkbox input and when using with ActiveForm & ActiveField. 
// Enable `autoLabel` property to auto style and position your labels, and disable 
// the default label of ActiveField (using `label(false)` method).
echo $form->field($model, 'status_1')->widget(CheckboxX::classname(), [
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true
])->label(false);

// Initialize using a checkbox input. Along with autoLabel` enabled configure the 
// `labelSettings` to set your own labels, styles and position them to left and right.
echo CheckboxX::widget([
    'name' => 'kv-adv-1',
    'value' => 1,
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true,
    'labelSettings' => [
        'label' => 'Left Label',
        'position' => CheckboxX::LABEL_LEFT
    ]
]); 
echo CheckboxX::widget([
    'name' => 'kv-adv-2',
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true,
    'labelSettings' => [
        'label' => 'Right Label',
        'position' => CheckboxX::LABEL_RIGHT
    ]
]);

// Auto style disabled and readonly labels.
echo CheckboxX::widget([
    'name' => 'kv-adv-3',
    'value' => 1,
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true,
    'disabled' => true,
    'labelSettings' => ['label' => 'Disabled']
]); 
echo CheckboxX::widget([
    'name' => 'kv-adv-4',
    'value' => 1,
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true,
    'readonly' => true,
    'labelSettings' => ['label' => 'Readonly']
]);

// Use customized HTML markup as checkbox indicators. Also set your own 
// advanced label styles.
echo CheckboxX::widget([
    'name' => 'kv-adv-5',
    'value' => 1,
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true,
    'pluginOptions' => [
        'iconChecked' => '<b>&check;</b>',
        'iconUnchecked' => '<b>X</b>',
    ],
    'labelSettings' => ['label' => 'Blue Normal', 'options'=>['class'=>'text-info']]
]);
echo CheckboxX::widget([
    'name' => 'kv-adv-6',
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'autoLabel' => true,
    'pluginOptions' => [
        'size'=>'sm',
        'iconChecked' => '<b>&check;</b>',
        'iconUnchecked' => '<b>X</b>',
    ],
    'labelSettings' => ['label' => 'Blue Small', 'options'=>['class'=>'text-info']]
]);

// Use native checkboxes with enabled tri state behavior and enclosed label.
echo '<div class="checkbox">';
echo '<label class="control-label" for="kv-adv-7">';
echo CheckboxX::widget([
    'name' => 'kv-adv-7',
    'initInputType' => CheckboxX::INPUT_CHECKBOX,
    'options'=>['id'=>'kv-adv-7'],
    'pluginOptions' => [
        'useNative' => true,
        'enclosedLabel' => true
    ]
]);
echo 'Native 3-state';
echo '</label>';
echo '</div>';


<!-- Krajee Flat Blue Theme -->
<legend><small>Krajee Flat Blue Theme</small></legend>
<div class="form-group">
    <label class="cbx-label" for="kv-adv-8">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-8',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-8'],
        'pluginOptions' => [
            'theme' => 'krajee-flatblue',
            'enclosedLabel' => true
        ]
    ]); ?>
    Default
    </label>
</div>
<div class="form-group has-success">
    <label class="cbx-label" for="kv-adv-9">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-9',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-9'],
        'pluginOptions' => [
            'theme' => 'krajee-flatblue',
            'enclosedLabel' => true
        ]
    ]); ?>
    Success
    </label>
</div>
<div class="form-group has-error">
    <label class="cbx-label" for="kv-adv-10">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-10',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-10'],
        'pluginOptions' => [
            'theme' => 'krajee-flatblue',
            'enclosedLabel' => true
        ]
    ]); ?>
    Error
    </label>
</div>
<div class="form-group has-warning">
    <label class="cbx-label" for="kv-adv-11">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-11',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-11'],
        'pluginOptions' => [
            'theme' => 'krajee-flatblue',
            'enclosedLabel' => true
        ]
    ]); ?>
    Warning
    </label>
</div>
<!-- Default Theme -->
<legend><small>Default Theme</small></legend>
<div class="form-group">
    <label class="cbx-label" for="kv-adv-118">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-118',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-118'],
        'pluginOptions' => [
            'enclosedLabel' => true
        ]
    ]); ?>
    Default
    </label>
</div>
<div class="form-group has-success">
    <label class="cbx-label" for="kv-adv-119">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-119',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-119'],
        'pluginOptions' => [
            'enclosedLabel' => true
        ]
    ]); ?>
    Success
    </label>
</div>
<div class="form-group has-error">
    <label class="cbx-label" for="kv-adv-1110">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-1110',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-1110'],
        'pluginOptions' => [
            'enclosedLabel' => true
        ]
    ]); ?>
    Error
    </label>
</div>
<div class="form-group has-warning">
    <label class="cbx-label" for="kv-adv-1111">
    <?= CheckboxX::widget([
        'name' => 'kv-adv-1111',
        'initInputType' => CheckboxX::INPUT_CHECKBOX,
        'options'=>['id'=>'kv-adv-1111'],
        'pluginOptions' => [
            'enclosedLabel' => true
        ]
    ]); ?>
    Warning
    </label>
</div

yii2-checkbox-x is released under the BSD 3-Clause License. See the bundled LICENSE.md for details.