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 5.x / 4.x / 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 library 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).
Not seeing the updated content on this page! Hard refresh your browser to clean cache for this page (e.g. SHIFT-F5 on Windows Chrome)
CheckboxX supports configuration of the bootstrap library version so that you can use this either with any Bootstrap version 3.x and above. For setting up the bootstrap version for your extension, you can configure the CheckboxX::bsVersion property to one of the following.
To use with bootstrap 3 library - you can set CheckboxX::bsVersion property to any string starting with 3 (e.g. 3 or 3.3.7 or 3.x)
To use with bootstrap 4 library - you can set CheckboxX::bsVersion property to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)
To use with bootstrap 5 library - you can set CheckboxX::bsVersion property to any string starting with 5 (e.g. 5 or 5.1.0 or 5.x)
Generally, you may also want to set a default version globally for all Krajee Extensions (instead of setting it for each widget or extension separately). In order to do this, you can setup the bsVersion property within Yii 2 application params (i.e. Yii::$app->params['bsVersion']). To set this up, add this section of code to your application params configuration file (e.g. config/params.php):
'params' => [
'bsVersion' => '5.x', // this will set globally `bsVersion` to Bootstrap 5.x for all Krajee Extensions
// other settings
// 'adminEmail' => 'admin@example.com'
]
If CheckboxX::bsVersion property is set, in addition to Yii::$app->params['bsVersion'], the extension level setting (CheckboxX::bsVersion property) will override the Yii::$app->params['bsVersion']. If CheckboxX::bsVersion property is not set, and Yii::$app->params['bsVersion'] is also not set, CheckboxX::bsVersion property will default to 3.x (i.e. Bootstrap 3.x version will be assumed as default).
You need to install one of yiisoft/yii2-bootstrap or yiisoft/yii2-bootstrap4 or yiisoft/yii2-bootstrap5 extensions manually in your application to enable Bootstrap 3.x or 4.x or 5.x functionality respectively. This dependency has not been pre-built into the composer configuration for Krajee extensions, to allow better control to the developers in configuring their bootstrap library version. If bsVersion is set to 5.x and yiisoft/yii2-bootstrap5 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap5 extension. If bsVersion is set to 4.x and yiisoft/yii2-bootstrap4 is not installed, then an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap4 extension. Similarly, if bsVersion is set to 3.x and yiisoft/yii2-bootstrap is not installed, an exception message will be thrown mentioning you to install the yiisoft/yii2-bootstrap extension.
To install yiisoft/yii2-bootstrap5, add the repo to the require section of your application's composer.json.
"yiisoft/yii2-bootstrap5": "@dev"
To install yiisoft/yii2-bootstrap4, add the repo to the require section of your application's composer.json.
"yiisoft/yii2-bootstrap4": "@dev"
To install yiisoft/yii2-bootstrap, add the repo to the require section of your application's composer.json.
"yiisoft/yii2-bootstrap": "@dev"
The Krajee extension asset bundle(s) by default depend on one of the following asset bundles to load the Bootstrap CSS and JS:
yii\bootstrap\BootstrapAsset and/or yii\bootstrap\BootstrapPluginAsset for bootstrap 3.x (bsVersion = 3 setting)
yii\bootstrap4\BootstrapAsset and/or yii\bootstrap4\BootstrapPluginAsset for bootstrap 4.x ( bsVersion = 4 setting)
yii\bootstrap5\BootstrapAsset and/or yii\bootstrap5\BootstrapPluginAsset for bootstrap 5.x (bsVersion = 5 setting)
This is controlled by the property bsDependencyEnabled within the asset bundle (which defaults to true). One can override this and prevent the default yii2 bootstrap assets (CSS & JS) from loading by doing one or all of the following:
Global Override: Set Yii::$app->params['bsDependencyEnabled'] to false in your Yii 2 application config params.php. This setting will be applied for all Krajee Extension Asset Bundles that depend on Bootstrap assets.
'params' => [
'bsDependencyEnabled' => false, // this will not load Bootstrap CSS and JS for all Krajee extensions
// you need to ensure you load the Bootstrap CSS/JS manually in your view layout before Krajee CSS/JS assets
//
// other params settings below
// 'bsVersion' => '5.x',
// 'adminEmail' => 'admin@example.com'
]
Asset Bundle Specific Override: Set bsDependencyEnabled to false for the specific asset bundle within Yii2 Asset Manager component in your Yii 2 application config file.
// ...
'components' => [
'assetManager' => [
'bundles' => [
'kartik\form\ActiveFormAsset' => [
'bsDependencyEnabled' => false // do not load bootstrap assets for a specific asset bundle
],
],
],
],
When setting bsDependencyEnabled to false, you need to ensure that your app code/view layout loads the Bootstrap CSS and JS on your view before the Krajee CSS/JS are loaded to ensure that the Krajee extension JS plugins and CSS styles do not get broken.
Bootstrap 5.x / 4.x does not include glyphicons or any other icons framework bundled with the library. Krajee extensions therefore will use Font Awesome 5.x icons instead of glyphicons when working with Bootstrap 5.x / 4.x. You can download Font Awesome 5.x icons from the icons website. Alternatively, you can load the free version of Font Awesome from their CDN.
For Krajee extensions and demos, the Font Awesome Free version is used and loaded as the Icons Display Package on all the Yii2 demo layouts. To include font awesome assets on your page, include the following markup on the HEAD section of your view layout file, when bsVersion is set to 4.x or 5.x.
Option 1: Font CSS version of Font Awesome:
<!-- on your view layout file HEAD section --> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css">
Option 2: SVG / JS version of Font Awesome (recommended for cleaner scaling vector icons and features like icon layers):
<!-- on your view layout file HEAD section --> <script defer src="https://use.fontawesome.com/releases/v5.3.1/js/all.js" crossorigin="anonymous"></script>
Alternatively, you can use the FontAwesomeAsset from the kartik-v/yii2-icons package to load the SVG/JS version.
// on your view layout file use kartik\icons\FontAwesomeAsset; FontAwesomeAsset::register($this);
The yii2-checkbox-x extension can be installed automatically or manually using one of these options:
Installation via Composer is the recommended and most easy option to install Krajee Yii2 extensions. You can install yii2-checkbox-x via composer package manager. Either run:
$ php composer.phar require kartik-v/yii2-checkbox-x "dev-master"
or add:
"kartik-v/yii2-checkbox-x": "dev-master"
to your application's composer.json file.
You may also manually install the extension to your project (in case your composer install does not work). Just download the source ZIP or TAR ball and extract the extension asset files and folders into your project. You may need to install dependencies manually and also set the namespaces to the extensions in your Yii2 extensions configurations manually.
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:
bsVersion:
string | int, the bootstrap library version to be used for the extension. Refer the Bootstrap Info section for details and pre-requisites on setting this property.
To use with Bootstrap library - you can set this to any string starting with
3 (e.g. 3 or 3.3.7 or 4.x / 3.x)
To use with bootstrap 4 - you can set this to any string starting with
4 (e.g. 4 or 4.6.0 or 4.x)
To use with bootstrap 5 - you can set this to any string starting with
4 (e.g. 5 or 5.1.0 or 5.x)
bsColCssPrefixes:
array, the bootstrap grid column css prefixes mapping, the key is the bootstrap versions, and the value is an array containing the sizes and their corresponding grid column css prefixes. The class using this trait, must implement kartik\base\BootstrapInterface. If not set will default to:.
[
3 => [
self::SIZE_X_SMALL => 'col-xs-',
self::SIZE_SMALL => 'col-sm-',
self::SIZE_MEDIUM => 'col-md-',
self::SIZE_LARGE => 'col-lg-',
self::SIZE_X_LARGE => 'col-lg-',
self::SIZE_XX_LARGE => 'col-lg-',
],
4 => [
self::SIZE_X_SMALL => 'col-',
self::SIZE_SMALL => 'col-sm-',
self::SIZE_MEDIUM => 'col-md-',
self::SIZE_LARGE => 'col-lg-',
self::SIZE_X_LARGE => 'col-xl-',
self::SIZE_XX_LARGE => 'col-xl-',
],
5 => [
self::SIZE_X_SMALL => 'col-',
self::SIZE_SMALL => 'col-sm-',
self::SIZE_MEDIUM => 'col-md-',
self::SIZE_LARGE => 'col-lg-',
self::SIZE_X_LARGE => 'col-xl-',
self::SIZE_XX_LARGE => 'col-xxl-',
],
];
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"); }",
];
use kartik\checkbox\CheckboxX;
use kartik\form\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="fas fa-plus"></i>',
'iconUnchecked'=>'<i class="fas fa-minus"></i>',
'iconNull'=>'<i class="fas fa-times"></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();
use kartik\checkbox\CheckboxX;
use kartik\form\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>✓</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>✓</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="mb-2">
<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="mb-2 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="mb-2 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="mb-2 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="mb-2">
<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="mb-2 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="mb-2 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="mb-2 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.
Comments & Discussion
Note
You can now visit the Krajee Webtips Q & A forum for searching OR asking questions OR helping programmers with answers on these extensions and plugins. For asking a question click here. Select the appropriate question category (i.e. Krajee Plugins) and choose this current page plugin in the question related to field.
The comments and discussion section below are intended for generic discussions or feedback for this plugin. Developers may not be able to search or lookup here specific questions or tips on usage for this plugin.