The enhanced ActiveForm widget and ActiveField component allows you to control specific Bootstrap library features for Horizontal Forms, Input Groups, and includes more customized inputs.
\kartik\widgets
namespace, this widget can be also installed from the yii2-widget-activeform repository
and can also be accessed via \kartik\form\ActiveForm
or \kartik\form\ActiveField
namespaces.
The kartik\form\ActiveForm widget requires the extended kartik\form\ActiveField component to provide all functionality.
Ensure, this pre-requisite is complied with in your widget calls. Any customization should
be done by extending these kartik\form\ActiveForm
or kartik\form\ActiveField
classes.
For explanation on using complex form layouts (e.g. inline form fields with bootstrap horizontal form), you can refer this web-tip.
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)
ActiveForm
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 ActiveForm::bsVersion
property to one of the following.
To use with bootstrap 3 library - you can set ActiveForm::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 ActiveForm::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 ActiveForm::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 ActiveForm::bsVersion
property is set, in addition to Yii::$app->params['bsVersion']
, the extension level setting (ActiveForm::bsVersion
property) will override the Yii::$app->params['bsVersion']
. If ActiveForm::bsVersion
property is not set, and Yii::$app->params['bsVersion']
is also not set, ActiveForm::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 kartik\form\ActiveField
class supports all properties as defined within yii\widgets\ActiveField. The following additional properties are supported:
The bootstrap input group addon configuration. Typically supported for input, select, and password inputs. The following settings can be configured:
prepend
: array the prepend addon configuration, where you set the following keys:
content
: string the prepend addon content
asButton
: boolean whether the addon is a button or button group. Defaults to false
.
options
: array HTML attributes for the prepend addon
append
: array the append addon configuration, where you set the following keys:
content
: string the append addon content
asButton
: boolean whether the addon is a button or button group. Defaults to false
.
options
: array HTML attributes for the append addon
groupOptions
: array HTML options for the input group
contentBefore
: string content placed before addon. This is not HTML encoded.
contentAfter
: string content placed after addon. This is not HTML encoded.
boolean, whether the label is to be hidden and auto-displayed as a placeholder. Defaults to false
for vertical/horizontal forms and true
for inline forms.
boolean, whether to auto offset toggle inputs (checkboxes / radios) horizontal form layout for BS 4.x forms. This will read the labelSpan
and automatically offset the checkboxes/radios. Defaults to true
.
string, the template for rendering checkboxes and radios for a default Bootstrap markup with an enclosed label. Defaults to:
{beginLabel}\n{input}\n{labelTitle}\n{endLabel}\n{error}\n{hint}
string, the template for rendering checkboxes and radios for a default Bootstrap markup without an enclosed label. Defaults to:
{input}\n{label}\n{error}\n{hint}
array, the HTML attributes for the container wrapping BS4 checkbox or radio controls within which the content
will be rendered via the checkTemplate or checkEnclosedTemplate. Defaults to an empty array []
.
The extension automatically parse for Bootstrap 5.x / 4.x / 3.x styles and add the necessary CSS classes to the checkbox/radio wrapper container.
string, the content to be placed before the error. Defaults to an empty string ''
.
string, the content to be placed before the field within the form group at the beginning. Defaults to an empty string ''
.
string, the content to be placed after the field within the form group at the end. Defaults to an empty string ''
.
string, the content to be placed before the input. Defaults to an empty string ''
.
string, the content to be placed before the label. Defaults to an empty string ''
.
string, the template for rendering the Bootstrap 5.x / 4.x custom file browser control. Defaults to:
<div class="custom-file">\n{input}\n{label}\n</div>\n{error}\n{hint}
string, one of the bootstrap size modifiers as mentioned below:
ActiveForm::SIZE_XS
or 'xs'
: Extra Small size
ActiveForm::SIZE_SM
or 'sm'
: Small size
ActiveForm::SIZE_MD
or 'md'
: Medium size
ActiveForm::SIZE_LG
or 'lg'
: Large size
ActiveForm::SIZE_XL
or 'xl'
: Extra Large size
boolean, whether to render the error. Defaults to true
except for inline form layout type.
array, the configuration for the feedback icon (applicable for bootstrap text inputs). This must be setup as an array containing the following keys:
type
: string, the icon type to use. Should be one of raw
or icon
. Defaults to icon
, where the default
, error
and success
settings will be treated as an icon CSS suffix name. If set to raw
, they will be treated as a raw content markup.
prefix
: string, the icon CSS class prefix to use if type
is icon
. Defaults to fas fa-
.
default
: string, the icon (CSS class suffix name or raw markup) to show by default. If not set will not be shown.
error
: string, the icon (CSS class suffix name or raw markup) to use when input has an error validation.
If not set will not be shown.
success
: string, the icon (CSS class suffix name or raw markup) to use when input has a success validation.
If not set will not be shown.
defaultOptions
: array, the HTML attributes to apply for default icon. The special attribute description
can be set to describe this feedback as an aria
attribute for accessibility. Defaults to (default)
.
errorOptions
: array, the HTML attributes to apply for error icon. The special attribute description
can be set to describe this feedback as an aria
attribute for accessibility. Defaults to (error)
.
successOptions
: array, the HTML attributes to apply for success icon. The special attribute description
can be set to describe this feedback as an aria
attribute for accessibility. Defaults to (success)
.
boolean, whether to highlight error and success states using Bootstrap 5.x / 4.x / 3.x styles on input group addons automatically. Defaults to true
.
array, the settings for displaying the hint. These settings are parsed only if hintType is set to
ActiveField::HINT_SPECIAL
. The following settings are supported:
showIcon
: boolean, whether to display the hint via a help icon indicator. Defaults to true
.
icon
: string, the markup to display the help icon. Defaults to:
<i class="fas fa-question-sign text-info"></i>
for Bootstrap 5.x / 4.x / 3.x.
<i class="fas fa-question-circle text-info"></i>
for Bootstrap 5.x / 4.x.
iconBesideInput
: boolean, whether to display the icon beside the input. Defaults to false
. The following
actions will be taken based on this setting:
if set to false
the help icon is displayed beside the label and the labelTemplate
setting is used to
render the icon and label markups.
if set to true
the help icon is displayed beside the input and the inputTemplate
setting is used to
render the icon and input markups.
labelTemplate
: string, the template to render the help icon and the field label. Defaults to {label}{help}
,
where:
{label}
will be replaced by the ActiveField label content.
{help}
will be replaced by the help icon indicator markup.
inputTemplate
: string, the template to render the help icon and the field input. Defaults to:
'<div style="width:90%; float:left">{input}</div><div style="padding-top:7px">{help}</div>'where:
{input}
will be replaced by the ActiveField input content
{help}
will be replaced by the help icon indicator markup
onLabelClick
: boolean, whether to display the hint on clicking the label. Defaults to false
.
onLabelHover
: boolean, whether to display the hint on hover of the label. Defaults to true
.
onIconClick
: boolean, whether to display the hint on clicking the icon. Defaults to true
.
onIconHover
: boolean, whether to display the hint on hover of the icon. Defaults to false
.
iconCssClass
: string, the CSS class appended to the span
container enclosing the icon.
labelCssClass
: string, the CSS class appended to the span
container enclosing label text within label tag.
contentCssClass
: string, the CSS class appended to the span
container displaying help content within
popover.
hideOnEscape
: boolean, whether to hide the popover on clicking escape button on the keyboard. Defaults to true
.
hideOnClickOut
: boolean, whether to hide the popover on clicking outside the popover. Defaults to true
.
title
: string, the title heading for the popover dialog. Defaults to empty string, whereby the heading is not
displayed.
placement
: string, the placement of the help popover on hover or click of the icon or label. Defaults to
top
.
container
: string, the specific element to which the popover will be appended to. Defaults to table
when
iconBesideInput
within hintSettings is set to true
, else defaults to form
animation
: boolean, whether to add a CSS fade transition effect when opening and closing the popover. Defaults to
true
.
delay
: integer|array, the number of milliseconds it will take to open and close the popover. Defaults to 0
.
selector
: integer, the specified selector to add the popover to. Defaults to boolean false
.
viewport
: string|array, the element within which the popover will be bounded to. Defaults to
['selector' => 'body', 'padding' => 0]
.
integer, the hint display type. If set to ActiveField::HINT_DEFAULT
, the hint will be displayed as a text block below
each input. If set to ActiveField::HINT_SPECIAL
, then the hintSettings will be applied to display the field
hint. Defaults to ActiveField::HINT_DEFAULT
.
array, CSS grid classes for horizontal layout. This must be setup as an array with these keys:
offset
: string, the offset grid class to append to the wrapper if no label is rendered
label
: string, the label grid class
wrapper
: string, the wrapper grid class
error
: string, the error grid class
hint
: string, the hint grid class
These options are compatible and similar to \yii\bootstrap\ActiveForm
and/or \yii\bootstrap5\ActiveForm
and provide a complete flexible
container. If labelSpan
is set in ActiveForm::formConfig
and wrapper
is also set, then both css options
are concatenated. If wrapper
contains a 'col-'
class wrapper, it overrides the tag from labelSpan
.
boolean, whether to render the wrapper in the template if wrapperOptions is empty. Defaults to true
.
boolean, whether to show errors for the field. Defaults to the showErrors
setting within \kartikorm\ActiveForm::formConfig
for the configured form type.
boolean, whether to show hints for the field. Defaults to the showHints
setting within \kartikorm\ActiveForm::formConfig
for the configured form type.
boolean|string, whether to show labels for the field. Defaults to the showLabels
setting within \kartikorm\ActiveForm::formConfig
for the configured form type. Should be one of the following values:
true
: shows labels for the field.
false
: hides labels for the field.
ActiveForm::SCREEN_READER
: shows labels in screen reader only (hide from normal display).
boolean, whether to show required asterisk/star indicator after each field label when the model attribute is set to have a required
validation rule. Defaults to true
. This will add a CSS class has-star
to the label and show the required asterisk/star after the label based on CSS ::after
styles. If you want any other label markup to show a required asterisk for a required model attribute field, then just add the CSS class has-star
to the label/span markup element within the active field container with CSS class form-group mb-3
.
NOTE: You can also alternatively add the CSS class is-required
to force any label / markup to show a red asterisk/star after the content.
boolean, whether to override the form layout styles and skip field formatting as per the form layout. Defaults to false
.
string, the static value for the field to be displayed for the static input OR when the form is in
staticOnly
mode. This value is not HTML encoded.
string, the active field markup template. Inherits and overrides values from parent class. This defaults to:
{label}\n{beginWrapper}\n{input}\n{hint}\n{error}\n{endWrapper}.
The following tokens are supported:
{beginLabel}
: Container begin tag for labels (to be used typically along with {labelTitle}
token, when you do not wish to directly use the {label}
token).
{labelTitle}
: Label content without tags (to be used typically when you do not wish to directly use the {label}
token).
{endLabel}
: Container end tag for labels (to be used typically with {labelTitle}
token, when you do not wish to directly use the {label}
token).
{label}
: Full label content enclosed within the label
tag.
{beginWrapper}
: Container for input,error and hint start tag. Uses a <div>
tag if there is a input wrapper CSS detected, else defaults to empty string.
{input}
: placeholder for input control
{hint}
: placeholder for hint/help text including sub container
{error}
: placeholder for error text including sub container
{endWrapper}
: end tag for {beginWrapper}
. Defaults to </div>
, if there is a input wrapper CSS detected, else defaults to empty string.
array,options for the wrapper tag, used in the {beginWrapper}
token within template.
addon
property to your field's inputOptions
. Refer the addon property for understanding the configuration options supported.
echo $form->field($model, 'amount_paid', [ 'addon' => ['append' => ['content'=>'.00']], ]);
echo $form->field($model, 'phone', [ 'addon' => ['prepend' => ['content'=>'<i class="fas fa-mobile-alt"></i>']] ]);
echo $form->field($model, 'include_text', [ 'addon' => ['prepend' => ['content'=>'<input type="checkbox">']] ]);
echo $form->field($model, 'username', [ 'addon' => [ 'append' => [ 'content' => Html::button('Go', ['class'=>'btn btn-primary']), 'asButton' => true ] ] ]);
kartik\bs5dropdown\ButtonDropdown use kartik\bs5dropdown\ButtonDropdown; echo $form->field($model, 'username', [ 'addon' => [ 'append' => [ 'content' => ButtonDropdown::widget([ 'label' => 'Action', 'dropdown' => [ 'items' => [ ['label' => 'Another action', 'url' => '#'], ['label' => 'Something else', 'url' => '#'], '<div class="dropdown-divider"></div>' // or use following for BS3 // '<li class="divider"></li>', ['label' => 'Separated link', 'url' => '#'], ], ], 'buttonOptions' => ['class'=>'btn-secondary'], 'renderContainer' => false ]), 'asButton' => true ] ] ]);
use yii\helpers\Html; use kartik\bs5dropdown\ButtonDropdown; echo $form->field($model, 'username', [ 'addon' => [ 'append' => [ 'content' => Html::button('Car', ['class'=>'btn btn-outline-secondary']) . " " . Html::button('Bus', ['class'=>'btn btn-outline-secondary']) . " " . ButtonDropdown::widget([ 'label' => 'Air', 'dropdown' => [ 'items' => [ ['label' => 'Another action', 'url' => '#'], ['label' => 'Something else', 'url' => '#'], '<div class="dropdown-divider"></div>' // or use following for BS3 // '<li class="divider"></li>', ['label' => 'Separated link', 'url' => '#'], ], ], 'buttonOptions' => ['class'=>'btn-outline-secondary'], 'renderContainer' => false ]), 'asButton' => true ] ] ]);
echo $form->field($model, 'date_1', [ 'addon' => [ 'prepend' => ['content'=>'<i class="fas fa-calendar-alt"></i>'], 'append' => ['content'=>'<button class="btn btn-secondary btn-default">Go</button>', 'asButton'=>true] ] ]);
// Controlling addon HTML options echo $form->field($model, 'amount_paid', [ 'addon' => [ 'prepend' => ['content' => '$', 'options'=>['class'=>'alert-success']], 'append' => ['content' => '.00', 'options'=>['style' => 'font-family: Monaco, Consolas, monospace;']], ] ]); // Displaying a SMALL input group echo $form->field($model, 'date_2', [ 'labelOptions' => ['class' => 'col-form-label-sm'], 'addon' => [ 'append' => [ ['content' => 'to'], ], 'contentAfter' => '<input type="text" id="date-to-2" class="form-control" placeholder="End Date" style="margin-left:-1px">', 'groupOptions' => ['class'=>'input-group-sm'] ] ]); // Displaying a LARGE input echo $form->field($model, 'date_3', [ 'labelOptions' => ['class' => 'col-form-label-lg'], 'addon' => [ 'append' => [ ['content' => 'to'], '<input type="text" id="date-to" class="form-control" placeholder="End Date">' ], 'contentAfter' => '<input type="text" id="date-to-3" class="form-control" placeholder="End Date" style="margin-left:-1px">', 'groupOptions' => ['class'=>'input-group-lg'] ] ]);
echo $form->field($model, 'address_1', [ 'addon' => [ 'prepend' => [ ['content' => '<i class="fas fa-volume-off"></i>'], ['content' => '<i class="fas fa-volume-down"></i>'], ['content' => '<i class="fas fa-volume-up"></i>'], ], 'append' => [ ['content' => '<i class="fas fa-stop"></i>'], ['content' => '<i class="fas fa-pause"></i>'], ['content' => '<i class="fas fa-play-circle"></i>'], ], ] ])->label('Music File');
Feedback icons can be embedded in text input controls as described in bootstrap optional icons section in form input styling. Refer the feedbackIcon property for understanding the configuration options available.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); // basic feedback icon echo $form->field($model, 'phone_1', [ 'feedbackIcon' => ['default' => 'phone'] ])->textInput(['placeholder'=>'Enter phone number...']); // multiple feedback icons echo $form->field($model, 'email_2', [ 'feedbackIcon' => [ 'prefix' => 'fas fa-', 'default' => 'envelope', 'success' => 'check text-success', 'error' => 'exclamation-triangle text-danger', 'defaultOptions' => ['class'=>'text-primary'] ] ])->textInput(['placeholder'=>'Enter a valid email address...']); // different icon prefixes echo $form->field($model, 'user_2', [ 'feedbackIcon' => [ 'prefix' => 'fas fa-', 'default' => 'user', 'success' => 'user-plus', 'error' => 'user-times', 'defaultOptions' => ['class'=>'text-warning'] ] ])->textInput(['placeholder'=>'Enter username...']); // feedback for input widgets instead of text inputs echo $form->field($model, 'phone_2', [ 'feedbackIcon' => [ 'prefix' => 'fas fa-', 'default' => 'mobile-alt', 'success' => 'check-circle', 'error' => 'exclamation-circle', ] ])->widget('yii\widgets\MaskedInput', [ 'mask' => '999-999-9999' ]); ActiveForm::end();
The ActiveField object supports ability to add and configure hints to each field. Hints for each Yii ActiveField are automatically displayed, if you set a hint for the attribute via model's attributeHints
method. Alternatively you can chain the ActiveField hint
method to set hints. The Krajee ActiveField allows the following additional hint settings and properties that allow you to configure hints for each field.
hintType
: int, the type of hint to be displayed. Defaults to ActiveField::HINT_DEFAULT
. Should be one of:
ActiveField::HINT_DEFAULT
or 1
: This shows the default hint rendered by yii active field below each input field.
ActiveField::HINT_SPECIAL
or 2
: This allows special and advanced hint display via a help icon indicator and/or label click/hover. The special hint display can be configured via hintSettings
.
hintSettings
: array, the settings for displaying the hint. These settings are parsed only if hintType
is set to ActiveField::HINT_SPECIAL
. This is setup as an array and allows configuring the following keys:
showIcon
: bool, whether to display the hint via a help icon indicator. Defaults to true
.
icon
: string, the markup to display the help icon. Defaults to <i class="fas fa-question-sign
text-info"></i>
.
iconBesideInput
: bool, whether to display the icon beside the input. Defaults to false
. The following
actions will be taken based on this setting:
if set to false
the help icon is displayed beside the label and the labelTemplate
setting is used to
render the icon and label markups.
if set to true
the help icon is displayed beside the input and the inputTemplate
setting is used to
render the icon and input markups.
labelTemplate
: string, the template to render the help icon and the field label. Defaults to {label}{help}
,
where:
{label}
will be replaced by the ActiveField label content
{help}
will be replaced by the help icon indicator markup
inputTemplate
: string, the template to render the help icon and the field input. Defaults to: <table
style="width:100%"><tr><td>{input}</td><td style="width:5%">{help}</td></tr></table>
, where:
{input}
will be replaced by the ActiveField input content
{help}
will be replaced by the help icon indicator markup
onLabelClick
: bool, whether to display the hint on clicking the label. Defaults to false
.
onLabelHover
: bool, whether to display the hint on hover of the label. Defaults to true
.
onIconClick
: bool, whether to display the hint on clicking the icon. Defaults to true
.
onIconHover
: bool, whether to display the hint on hover of the icon. Defaults to false
.
iconCssClass
: string, the CSS class appended to the span
container enclosing the icon.
labelCssClass
: string, the CSS class appended to the span
container enclosing label text within label tag.
contentCssClass
: string, the CSS class appended to the span
container displaying help content within popover.
hideOnEscape
: bool, whether to hide the popover on clicking escape button on the keyboard. Defaults to true
.
hideOnClickOut
: bool, whether to hide the popover on clicking outside the popover. Defaults to true
.
title
: string, the title heading for the popover dialog. Defaults to empty string, whereby the heading is not
displayed.
placement
: string, the placement of the help popover on hover or click of the icon or label. Defaults to
top
.
container
: string, the specific element to which the popover will be appended to. Defaults to table
when iconBesideInput is true
, else defaults to form
.
animation
: bool, whether to add a CSS fade transition effect when opening and closing the popover. Defaults to
true
.
delay
: int|array, the number of milliseconds it will take to open and close the popover. Defaults to 0
.
selector
: int, the specified selector to add the popover to. Defaults to boolean false
.
viewport
: string|array, the element within which the popover will be bounded to. Defaults to
['selector' => 'body', 'padding' => 0]
.
use kartik\form\ActiveForm; use kartik\form\ActiveField; $form = ActiveForm::begin(); // basic default hint set for the attribute via model's `attributeHints` method echo $form->field($model, 'email'); // special hint that displays hints via default settings i.e. `on click` of help icon indicator and // `on hover` of label. The hint is set for the attribute via model's `attributeHints` method. echo $form->field($model, 'email_1', ['hintType' => ActiveField::HINT_SPECIAL]); // custom special hint that is displayed by chaining the hint method. This example uses a text area as // input and also displays a input placeholder text. Set hint to show on click of label instead of hover // and set a custom placement (`right`) of the hint popover. echo $form->field($model, 'address', [ 'hintType' => ActiveField::HINT_SPECIAL, 'hintSettings' => ['placement' => 'right', 'onLabelClick' => true, 'onLabelHover' => false] ])->textArea([ 'id' => 'address-input', 'placeholder' => 'Enter address...', 'rows' => 4 ])->hint('Enter address in 4 lines. First 2 lines must contain the street details and next 2 lines the city, zip, and country detail.'); // Advanced hint settings and formatting. Hide icon indicator, display a hint title, and style your // hint content using HTML markup. echo $form->field($model, 'website', [ 'hintType' => ActiveField::HINT_SPECIAL, 'hintSettings' => [ 'showIcon' => false, 'title' => '<i class="fas fa-info-sign"></i> Note' ] ])->hint('Enter your <b>corporate website link</b> for a valid registration.'); // More hint settings. Show hint icon beside input instead of label and show on both click and/or hover // of icon (to support touch devices). Simultaneously, you can hide hints on hover and click of label. echo $form->field($model, 'notes', [ 'hintType' => ActiveField::HINT_SPECIAL, 'hintSettings' => [ 'iconBesideInput' => true, 'onLabelClick' => false, 'onLabelHover' => false, 'onIconClick' => true, 'onIconHover' => true, 'title' => '<i class="fas fa-info-sign"></i> Note' ] ])->hint('<div style="width:200px">Enter <b>valid notes</b> to identify this record.</div>'); ActiveForm::end();
contentBeforeInput
: string any markup/content to be placed before the rendered input part of the widget
contentAfterInput
: string any markup/content to be placed after the rendered input part of the widget
echo $form->field($model, 'field', [ 'contentBeforeInput'=>Html::beginTag('div', ['class='col-sm-10']), 'contentAfterInput'=>Html::endTag('div'), ]);
View a complete demo on HTML5 inputs.
Renders a checkbox input. The following parameters are supported:
options
: array, the HTML attributes in terms of name-value pairs. The following options are specially handled:
uncheck
: string, the value associated with the uncheck state of the radio button. If not set, it will take the default value 0
. This method will render a hidden input so that if the checkbox is not checked and is submitted, the value of this attribute will still be submitted to the server via the hidden input. If you do not want any hidden input, you should explicitly set this option as null.
label
: string, a label displayed next to the checkbox. It will NOT be HTML-encoded. Therefore you can pass
in HTML code such as an image tag. If this is coming from end users, you should Html::encode()
or encode it to prevent XSS attacks.
When this option is specified, the checkbox will be enclosed by a label tag. If you do not want any label, you should
explicitly set this option as null
.
labelOptions
: array, the HTML attributes for the label tag. This is only used when the label
option is specified.
The rest of the options will be rendered as the attributes of the resulting tag. The values will
be HTML-encoded using Html::encode()
. If a value is null, the corresponding attribute will not be rendered.
If you set a custom id
for the input element, you may need to adjust the $selectors
accordingly.
enclosedByLabel
: boolean, whether to enclose the checkbox within the label. If true, the method will still use template
to layout the checkbox and the error message except that the checkbox is enclosed by the label tag.
The checkbox active field includes enhancements over the yii default checkbox and handles automatic offsetting of checkbox inputs for Horizontal Forms. As an example, check the Remember Me
input below.
<?php $form = ActiveForm::begin([ 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); ?> <?= $form->field($model, 'username')->textInput(['id' => 'username-cbx']) ?> <?= $form->field($model, 'password')->passwordInput(['id' => 'password-cbx']) ?> <?= $form->field($model, 'rememberMe')->checkbox() ?> <div class="form-group mb-3 row"> <div class="col-sm-3"></div> <div class="col-sm-9"> <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?> </div> </div> <?php ActiveForm::end(); ?>
Renders a radio input. The following parameters are supported:
options
: array, the HTML attributes in terms of name-value pairs. The following options are specially handled:
uncheck
: string, the value associated with the uncheck state of the radio button. If not set, it will take the default value 0
. This method will render a hidden input so that if the radio button is not checked and is submitted, the value of this attribute will still be submitted to the server via the hidden input. If you do not want any hidden input, you should explicitly set this option as null.
label
: string, a label displayed next to the radio. It will NOT be HTML-encoded. Therefore you can pass
in HTML code such as an image tag. If this is coming from end users, you should Html::encode()
or encode it to prevent XSS attacks.
When this option is specified, the radio will be enclosed by a label tag. If you do not want any label, you should
explicitly set this option as null
.
labelOptions
: array, the HTML attributes for the label tag. This is only used when the label
option is specified.
The rest of the options will be rendered as the attributes of the resulting tag. The values will
be HTML-encoded using Html::encode()
. If a value is null, the corresponding attribute will not be rendered.
If you set a custom id
for the input element, you may need to adjust the $selectors
accordingly.
enclosedByLabel
: boolean, whether to enclose the radio within the label. If true, the method will still use template
to layout the radio and the error message except that the radio is enclosed by the label tag.
The radio active field includes enhancements over the yii default radio and handles automatic offsetting of radio inputs for Horizontal Forms. As an example, check the Yes
and No
inputs below.
<?php $form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); ?> <?= $form->field($model, 'username') ?> <?= $form->field($model, 'password')->passwordInput() ?> <?= $form->field($model, 'yes')->radio() ?> <?= $form->field($model, 'no')->radio() ?> <div class="form-group mb-3 row"> <div class="col-sm-3"></div> <div class="col-sm-9"> <?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?> </div> </div> <?php ActiveForm::end(); ?>
inline
option to true. $form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); $list = [0 => 'Morning', 1 => 'Noon', 2 => 'Evening']; /* Display a stacked checkbox list */ echo $form->field($model, 'contact')->checkboxList($list); /* Display an inline checkbox list */ echo $form->field($model, 'contact')->checkboxList($list, ['inline'=>true]); ActiveForm::end();
inline
option to true. $form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); $list = [0 => 'Morning', 1 => 'Noon', 2 => 'Evening']; /* Display a stacked radio list */ echo $form->field($model, 'contact')->radioList($list); /* Display an inline radio list */ echo $form->field($model, 'contact')->radioList($list, ['inline'=>true]); ActiveForm::end();
Email Address
control below for a horizontal form. $form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); echo $form->field($model, 'username'); echo $form->field($model, 'email')->staticInput(); ActiveForm::end();
View a complete demo on HTML5 inputs.
$form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 6, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); /* Color input - works with Firefox, Google Chrome & Opera*/ echo $form->field($model, 'color')->input('color'); /* Range input - works with Google Chrome & Opera*/ echo $form->field($model, 'brightness')->input('range', ['class' => 'form-control-range']); /* Number input - works with Firefox, Google Chrome, Safari & Opera*/ $form->field($model, 'rating')->input('number', ['min'=>1, 'max'=>5, 'placeholder' => 'Enter a rating between 1 and 5...']) ?> /* Date selector input - works with Google Chrome & Opera */ echo $form->field($model, 'birthday')->input('date'); ActiveForm::end();
ActiveForm::bsVersion
set to 4.x
or 5.x
). The currently available Bootstrap custom controls are custom checkbox, custom radio, custom switch input, custom select, custom range, and custom file input. Renders a Bootstrap 4.x / 5.x custom checkbox control. You need to set the custom
setting to true
in options
parameter within ActiveField::checkbox
. Notice how the model validation rule triggers the error and success validation styles.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_1')->checkbox(['custom' => true]); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom switch control. You need to set the custom
setting to true
and switch
setting to true
within options
parameter within ActiveField::checkbox
.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_2')->checkbox(['custom' => true, 'switch' => true]); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom radio control. You need to set the custom
setting to true
in options
parameter within ActiveField::radio
.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_3')->radio(['custom' => true]); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom checkbox list. You need to set the custom
setting to true
in options
parameter within ActiveField::checkboxList
.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_4')->checkboxList( [0 => 'Morning', 1 => 'Noon', 2 => 'Evening'], ['custom' => true, 'id' => 'custom-checkbox-list'] ); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom radio list. You need to set the custom
setting to true
in options
parameter within ActiveField::radioList
.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_5')->radioList( [0 => 'Morning', 1 => 'Noon', 2 => 'Evening'], ['custom' => true, 'id' => 'custom-radio-list'] ); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x inline custom checkbox list. You need to set the custom
and inline
settings to true
in options
parameter within ActiveField::checkboxList
.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_6')->checkboxList( [0 => 'Morning', 1 => 'Noon', 2 => 'Evening'], ['custom' => true, 'inline' => true, 'id' => 'custom-checkbox-list-inline'] ); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x inline custom radio list. You need to set the custom
and inline
settings to true
in options
parameter within ActiveField::radioList
.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'check_7')->radioList( [0 => 'Morning', 1 => 'Noon', 2 => 'Evening'], ['custom' => true, 'inline' => true, 'id' => 'custom-radio-list-inline'] ); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom select. You need to set the custom
setting to true
within ActiveField::dropdownList
options
parameter. You can render large or small size controls by adding the CSS class custom-select-lg
or custom-select-sm
.
To render a multiple select listBox you can use the ActiveField::listBox
input and set the multiple
property to true
within the options
parameter.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'weekdays4')->dropdownList( $data = [0 => 'Sun', 1 => 'Mon', 2 => 'Tue', 3 => 'Wed', 4 => 'Thu', 5 => 'Fri', 6 => 'Sat'];, ['custom' => true, 'id' => 'weekdays4-custom', 'prompt' => 'Select ...'] ); echo $form->field($model, 'weekdays5')->dropdownList( $data = [0 => 'Sun', 1 => 'Mon', 2 => 'Tue', 3 => 'Wed', 4 => 'Thu', 5 => 'Fri', 6 => 'Sat'];, ['custom' => true, 'class' => 'custom-select-sm', 'id' => 'weekdays5-custom', 'prompt' => 'Select ...'] ); echo $form->field($model, 'weekdays6')->dropdownList( $data = [0 => 'Sun', 1 => 'Mon', 2 => 'Tue', 3 => 'Wed', 4 => 'Thu', 5 => 'Fri', 6 => 'Sat'];, ['custom' => true, 'class' => 'custom-select-lg', 'id' => 'weekdays6-custom', 'prompt' => 'Select ...'] ); echo $form->field($model, 'weekdays3')->listBox( $data = [0 => 'Sun', 1 => 'Mon', 2 => 'Tue', 3 => 'Wed', 4 => 'Thu', 5 => 'Fri', 6 => 'Sat'];, ['custom' => true, 'multiple' => true, 'id' => 'weekdays3-custom-listbox', 'prompt' => 'Select ...'] ); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom range input. You need to set the custom
setting to true
within options
parameter in ActiveField::input
and set the type
parameter to range
. You can also control the range minimum and maximum values via the min
and max
use kartik\form\ActiveForm; $form = ActiveForm::begin(); echo $form->field($model, 'brightness')->input('range', [ 'custom' => true, 'min' => 0, 'max' => 5, 'id' => 'brightness-custom' ]); ActiveForm::end();
Renders a Bootstrap 4.x / 5.x custom file input. You need to set the custom
setting to true
within options
parameter in ActiveField::fileInput
.
NOTE: The custom file input is animated via bs-custom-file-input plugin. The yii2-widget-activeform extension automatically initializes the plugin behavior for custom file input.
use kartik\form\ActiveForm; $form = ActiveForm::begin(); // English Input (Single File Example) echo $form->field($model, 'attachment_1')->fileInput(['custom' => true])->label('Select a file...'); // Spanish Input (Multiple Files Example) echo $form->field($model, 'attachment_2[]', ['labelOptions' => ['data-browse' => 'Elegir']]) ->fileInput(['custom' => true, 'multiple' => true, 'lang' => 'es'])->label('Seleccionar Archivo...'); ?> ActiveForm::end();
use kartik\form\ActiveForm; $form = ActiveForm::begin(); $data = [0 => 'Sun', 1 => 'Mon', 2 => 'Tue', 3 => 'Wed', 4 => 'Thu', 5 => 'Fri', 6 => 'Sat']; // Simple basic usage echo $form->field($model, 'weekdays1')->checkboxButtonGroup($data);?> $model->weekdays2 = [1, 3, 5]; // Change button group size, button styles, and preselect 'Mon', 'Wed', & 'Fri' echo $form->field($model, 'weekdays2')->checkboxButtonGroup($data, [ 'class' => 'btn-group-sm', 'itemOptions' => ['labelOptions' => ['class' => 'btn btn-warning']] ]); // Advanced usage - Disable selected checkboxes (e.g. 'Sun' & 'Sat') echo $form->field($model, 'weekdays3')->checkboxButtonGroup($data, ['disabledItems'=>[0, 6]]); ActiveForm::end();
use kartik\form\ActiveForm; $form = ActiveForm::begin(); $data = [0 => 'Sun', 1 => 'Mon', 2 => 'Tue', 3 => 'Wed', 4 => 'Thu', 5 => 'Fri', 6 => 'Sat']; // Simple basic usage echo $form->field($model, 'weekdays1')->radioButtonGroup($data);?> $model->weekdays2 = 1; // Change button group size, button styles, and preselect 'Mon' echo $form->field($model, 'weekdays2')->radioButtonGroup($data, [ 'class' => 'btn-group-sm', 'itemOptions' => ['labelOptions' => ['class' => 'btn btn-warning']] ]); // Advanced usage - Disable selected radios (e.g. 'Sun' & 'Sat') echo $form->field($model, 'weekdays3')->radioButtonGroup($data, ['disabledItems'=>[0, 6]]); ActiveForm::end();
checkboxList
and radioList
. It generates a scrolling multi select list box with checkboxes or radio for selection. The list array can be populated just like any Yii dropDownList
. The advantage of this multi-select is that it allows the labels to be HTML formatted. For the usage examples in this demo, the following HTML formatted values are used to populate this multi-select list.
use kartik\helpers\Html; $model->icons = [ 'align-left' => Html::icon('align-left') . ' Align Left', 'align-center' => Html::icon('align-center') . ' Align Center', 'align-right' => Html::icon('align-right') . ' Align Right', 'align-justify' => Html::icon('align-justify') . ' Align Justify', 'arrow-down' => Html::icon('arrow-down') . ' Direction Down', 'arrow-up' => Html::icon('arrow-up') . ' Direction Up', 'arrow-left' => Html::icon('arrow-left') . ' Direction Left', 'arrow-right' => Html::icon('arrow-right') . ' Direction Right', ];
$form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_VERTICAL ]); echo $form->field($model, 'select_data')->multiselect($model->icons); ActiveForm::end();
$form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_HORIZONTAL, 'formConfig' => ['labelSpan' => 3, 'deviceSize' => ActiveForm::SIZE_SMALL] ]); echo $form->field($model, 'select_data')->multiselect($model->icons); ActiveForm::end();
selector
property. $form = ActiveForm::begin([ 'id' => 'login-form' ]); echo $form->field($model, 'select_data')->multiselect($model->icons, ['selector'=>'radio']); ActiveForm::end();
145px
. You can override this by setting the height
property under the control options
. You can also set additional html options by configuring container
within the control options
array. $form = ActiveForm::begin([ 'id' => 'login-form', 'type' => ActiveForm::TYPE_VERTICAL ]); echo $form->field($model, 'select_data')->multiselect($model->icons, [ 'height' => '225px', 'container' => ['class' => 'bg-white'] ]); ActiveForm::end();
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.