ActiveField

API reference › Bootstrap 6 › ActiveField

class	`yii2\extensions\bootstrap6\ActiveField`
Extends	`yii\widgets\ActiveField` » `yii\base\Component` » `yii\base\BaseObject`
Implements	`yii\base\Configurable`
Source	`src/ActiveField.php`

Renders a Bootstrap 6 form field for the layouts of ActiveForm.

Markup per layout ({error} is the .invalid-feedback element, {hint} the .form-text element):

default: <div class="form-field mb-3"> + label, control, hint, and error stacked by the .form-field grid.
horizontal: <div class="row mb-3"> + <label class="sm:col-2 col-form-label"> + <div class="sm:col-10"> wrapping the control, hint, and error. Checkboxes and radios render <div class="sm:col-10 sm:offset-2"> + <div class="form-field">. Grid classes come from $horizontalCssClasses.
inline: the form is a row lg:row-cols-auto g-3 align-items-center grid and each field is <div class="col-12"> with a visually-hidden label, a placeholder, and no error. Checkboxes and radios render a nested <div class="form-field">.
floating: <div class="form-field mb-3"> + <div class="form-floating"> holding the label BEFORE the control, then hint and error outside the wrapper, as in the Bootstrap validation docs. The feedback is a sibling of the wrapper, not of the control, so the wrapper carries the error CSS class on the server when the attribute has errors. On the client, a :has() rule registered once per form displays the sibling feedback as soon as the control (or the container in ActiveForm::VALIDATION_STATE_ON_CONTAINER mode) carries the error CSS class, so any client validation layer works without jQuery. The feedback is not placed inside .form-floating because the absolutely positioned label spans the whole wrapper height, so the feedback would push the floated label over the control value.

Checkboxes, radios, and switches are rendered by Html (.check, .radio, .switch) with a plain label; the .form-field grid lays them out in two columns. Lists render one .form-field per item and the error after the list container, which receives the error CSS class. Size controls with form-control-sm or form-control-lg through $inputOptions or the per-call class option; dropDownList(), listBox(), and fileInput() keep form-control when a per-call class is given.

Besides the core placeholders, $template accepts {beginLabel}, {labelTitle}, {endLabel} (label parts), and {beginWrapper}, {endWrapper} (tags built from $wrapperOptions).

Properties

Property	Type	Description	Defined by
`$addAriaAttributes`	`bool`	Adds aria HTML attributes `aria-required` and `aria-invalid` for inputs Default: `true`. Available since 2.0.11.	`yii\widgets\ActiveField`
`$attribute`	`string`	The model attribute that this field is associated with. Default: `null`.	`yii\widgets\ActiveField`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$checkEnclosedTemplate`	`string`	Template for checkboxes and radios enclosed by their label. Default: `"{beginLabel}\n{input}\n{labelTitle}\n{endLabel}\n{hint}\n{error}"`.	`ActiveField`
`$checkHorizontalTemplate`	`string`	Template for checkboxes and radios in the horizontal layout. Default: `"{beginWrapper}\n<div class=\"form-field\">\n{input}\n{label}\n{hint}\n" . "{error}\n</div>\n{endWrapper}"`.	`ActiveField`
`$checkOptions`	`mixed[]`	Default options of `checkbox()` and of the `checkboxList()` items. Default: `[]`.	`ActiveField`
`$checkTemplate`	`string`	Template for checkboxes and radios; the inline layout wraps it in `<div class="form-field">`. Default: `"{input}\n{label}\n{hint}\n{error}"`.	`ActiveField`
`$enableAjaxValidation`	`bool\|null`	Whether to enable AJAX-based data validation. Default: `null`.	`yii\widgets\ActiveField`
`$enableClientValidation`	`bool\|null`	Whether to enable client-side data validation. Default: `null`.	`yii\widgets\ActiveField`
`$enableError`	`bool`	Whether to render the error element; `false` by default in the inline layout. Default: `true`.	`ActiveField`
`$enableLabel`	`bool`	Whether to render the label. Default: `true`.	`ActiveField`
`$errorOptions`	`mixed[]`	Default: `['class' => 'invalid-feedback']`.	`ActiveField`
`$form`	`yii\widgets\ActiveForm`	The form that this field is associated with. Default: `null`.	`yii\widgets\ActiveField`
`$hintOptions`	`mixed[]`	Default: `['class' => 'form-text']`.	`ActiveField`
`$horizontalCssClasses`	`mixed[]`	Grid classes of the horizontal layout, keyed by `error`, `field`, `hint`, `label`, `offset` (wrapper of fields without label), and `wrapper`. Default: `[]`.	`ActiveField`
`$inline`	`bool`	Whether `checkboxList()` and `radioList()` lay out their items horizontally. Default: `false`.	`ActiveField`
`$inputOptions`	`mixed[]`	Default: `['class' => 'form-control']`.	`ActiveField`
`$inputTemplate`	`string\|null`	Template wrapping the rendered control, for example an input group: `<div class="input-group">{input}</div>`. Default: `null`.	`ActiveField`
`$labelOptions`	`mixed[]`	Default: `['class' => 'form-label']`.	`ActiveField`
`$model`	`yii\base\Model`	The data model that this field is associated with. Default: `null`.	`yii\widgets\ActiveField`
`$options`	`mixed[]`	Default: `['class' => 'form-field mb-3']`.	`ActiveField`
`$parts`	`array`	Different parts of the field (e.g. input, label). Default: `[]`.	`yii\widgets\ActiveField`
`$radioOptions`	`mixed[]`	Default options of `radio()` and of the `radioList()` items. Default: `[]`.	`ActiveField`
`$selectors`	`array`	The jQuery selectors for selecting the container, input and error tags. Default: `[]`.	`yii\widgets\ActiveField`
`$template`	`string`	The template that is used to arrange the label, the input field, the error message and the hint text. Default: `"{label}\n{input}\n{hint}\n{error}"`.	`yii\widgets\ActiveField`
`$validateOnBlur`	`bool\|null`	Whether to perform validation when the input field loses focus. Default: `null`.	`yii\widgets\ActiveField`
`$validateOnChange`	`bool\|null`	Whether to perform validation when the value of the input field is changed. Default: `null`.	`yii\widgets\ActiveField`
`$validateOnType`	`bool\|null`	Whether to perform validation while the user is typing in the input field. Default: `null`.	`yii\widgets\ActiveField`
`$validationDelay`	`int\|null`	Number of milliseconds that the validation should be delayed when the user types in the field and `$validateOnType` is set `true`. Default: `null`.	`yii\widgets\ActiveField`
`$wrapperOptions`	`mixed[]`	HTML attributes of the `{beginWrapper}` tag; the `tag` option sets the tag name (default `div`). Default: `[]`.	`ActiveField`

Methods

Method	Description	Defined by
`__construct()`		`ActiveField`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Component`
`__get()`	Returns the value of a component property.	`yii\base\Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\Component`
`__set()`	Sets the value of a component property.	`yii\base\Component`
`__toString()`	PHP magic method that returns the string representation of this object.	`yii\widgets\ActiveField`
`__unset()`	Sets a component property to be null.	`yii\base\Component`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`begin()`	Renders the opening tag of the field container.	`yii\widgets\ActiveField`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\Component`
`checkbox()`	Renders a checkbox, or a switch with the `switch` option.	`ActiveField`
`checkboxList()`	Renders a list of checkboxes, see `Html::checkboxList()`.	`ActiveField`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`colorInput()`	Renders a color picker with the `form-control form-control-color` classes.	`ActiveField`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`dropDownList()`		`ActiveField`
`end()`	Renders the closing tag of the field container.	`yii\widgets\ActiveField`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`error()`		`ActiveField`
`fileInput()`	Merges `$inputOptions` before the core method, which skips them on Yii 2.0.x when they equal the core default `['class' => 'form-control']`.	`ActiveField`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`hiddenInput()`	Renders a hidden input.	`yii\widgets\ActiveField`
`hint()`		`ActiveField`
`init()`	Initializes the object.	`yii\base\BaseObject`
`inline()`	Sets whether `checkboxList()` and `radioList()` lay out their items horizontally.	`ActiveField`
`input()`		`ActiveField`
`label()`	Renders the label, or enables or disables it with a `bool` argument.	`ActiveField`
`listBox()`		`ActiveField`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`passwordInput()`		`ActiveField`
`radio()`	Renders a radio.	`ActiveField`
`radioList()`	Renders a list of radios, see `Html::radioList()`.	`ActiveField`
`rangeInput()`	Renders a range input wrapped in the `.form-range` element and registers the plugin bundle that initializes it.	`ActiveField`
`render()`		`ActiveField`
`staticControl()`	Renders a read-only plain-text control with the attribute value.	`ActiveField`
`textarea()`		`ActiveField`
`textInput()`		`ActiveField`
`trigger()`	Triggers an event.	`yii\base\Component`
`widget()`		`ActiveField`
`addAriaAttributes()` protected	Adds aria attributes to the input options.	`yii\widgets\ActiveField`
`addErrorClassIfNeeded()` protected	Adds validation class to the input options if needed.	`yii\widgets\ActiveField`
`addRoleAttributes()` protected	Add role attributes to the input options	`yii\widgets\ActiveField`
`adjustLabelFor()` protected	Adjusts the `for` attribute for the label based on the input options.	`yii\widgets\ActiveField`
`createLayoutConfig()` protected	Returns the layout-specific default configuration.	`ActiveField`
`generateLabel()` protected	Generates the label element based on `labelOptions` configuration when `enclosedByLabel` is `false`.	`yii\widgets\ActiveField`
`getClientOptions()` protected	Returns the JS options for the field.	`yii\widgets\ActiveField`
`getInputId()` protected	Returns the HTML `id` of the input element of this form field.	`yii\widgets\ActiveField`
`horizontalCssClass()` protected	Returns a grid class of `$horizontalCssClasses`, or an empty array when it is unset or empty.	`ActiveField`
`isAjaxValidationEnabled()` protected	Checks if ajax validation enabled for the field.	`yii\widgets\ActiveField`
`isClientValidationEnabled()` protected	Checks if client validation enabled for the field.	`yii\widgets\ActiveField`
`layout()` protected	Returns the layout of the owning form, or `ActiveForm::LAYOUT_DEFAULT` for a non-Bootstrap form.	`ActiveField`
`registerFloatingFeedbackStyle()` protected	Registers, once per form, the style rule that displays the feedback following a `.form-floating` wrapper when its control or its container carries the error CSS class. Whitespace-separated classes in `ActiveForm::$errorCssClass` are matched together; no rule is registered when it holds no class.	`ActiveField`
`renderBooleanInput()` protected	Renders a checkbox or radio with the layout-specific template and label.	`ActiveField`
`renderLabelParts()` protected	Renders the `{beginLabel}`, `{labelTitle}`, and `{endLabel}` parts.	`ActiveField`
`renderListInput()` protected	Renders a checkbox or radio list with the list label pointing to no control.	`ActiveField`
`renderWrapperParts()` protected	Builds the `{beginWrapper}` and `{endWrapper}` parts unless they are already set.	`ActiveField`

Method details

__construct()

public function __construct(array<string, mixed> $config = [])

Parameters

Parameter	Type	Description
`$config`	`array<string, mixed>`	Configuration merged over the defaults of `createLayoutConfig()`.

checkbox()

public function checkbox(mixed[] $options = [], bool $enclosedByLabel = false): static

Renders a checkbox, or a switch with the switch option.

Besides the options of Html::checkbox(), the following options are handled: label (false hides it), labelOptions, template, and wrapperOptions.

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Input attributes merged over `$checkOptions`.
`$enclosedByLabel`	`bool`	Whether to render the input inside the label (`$checkEnclosedTemplate`).

Returns

static

See also

checkboxList()

public function checkboxList(mixed[] $items, mixed[] $options = []): static

Renders a list of checkboxes, see Html::checkboxList().

Parameters

Parameter	Type	Description
`$items`	`mixed[]`	Data items, value => label.
`$options`	`mixed[]`	List options; `inline` defaults to `$inline`.

Returns

static

colorInput()

public function colorInput(mixed[] $options = []): static

Renders a color picker with the form-control form-control-color classes.

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Input attributes.

Returns

static

See also

https://getbootstrap.com/docs/6.0/forms/form-control/#color

dropDownList()

public function dropDownList(mixed[] $items, mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$items`	`mixed[]`	Option data items.
`$options`	`mixed[]`	Tag attributes; a `class` keeps `form-control`, and the `placeholder` of `$inputOptions` is not inherited.

Returns

static

error()

public function error(mixed[]|false $options = []): static

Parameters

Parameter	Type	Description
`$options`	`mixed[]\|false`	Tag attributes, or `false` to omit the error element.

Returns

static

fileInput()

public function fileInput(mixed[] $options = []): static

Merges $inputOptions before the core method, which skips them on Yii 2.0.x when they equal the core default ['class' => 'form-control'].

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Tag attributes; a `class` keeps `form-control`.

Returns

static

hint()

public function hint(bool|string|null $content, mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$content`	`bool\|string\|null`	Hint content, `null` for the model hint, or `false` to omit it.
`$options`	`mixed[]`	Tag attributes.

Returns

static

inline()

public function inline(bool $value = true): static

Sets whether checkboxList() and radioList() lay out their items horizontally.

Call it before the list method.

Parameters

Parameter	Type	Description
`$value`	`bool`

Returns

static

input()

public function input(string $type, mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$type`	`string`	Input type.
`$options`	`mixed[]`	Tag attributes merged over `$inputOptions`.

Returns

static

label()

public function label(bool|string|null $label = null, mixed[]|null $options = []): static

Renders the label, or enables or disables it with a bool argument.

Disabling the label in the horizontal layout adds the offset grid class to the wrapper.

Parameters

Parameter	Type	Description
`$label`	`bool\|string\|null`	Label content (not encoded), `null` for the model label, or a `bool`.
`$options`	`mixed[]\|null`	Tag attributes merged over `$labelOptions`.

Returns

static

listBox()

public function listBox(mixed[] $items, mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$items`	`mixed[]`	Option data items.
`$options`	`mixed[]`	Tag attributes; a `class` keeps `form-control`, and the `placeholder` of `$inputOptions` is not inherited.

Returns

static

passwordInput()

public function passwordInput(mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Tag attributes merged over `$inputOptions`.

Returns

static

radio()

public function radio(mixed[] $options = [], bool $enclosedByLabel = false): static

Renders a radio.

Accepts the same options as checkbox() except switch.

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Input attributes merged over `$radioOptions`.
`$enclosedByLabel`	`bool`	Whether to render the input inside the label (`$checkEnclosedTemplate`).

Returns

static

See also

https://getbootstrap.com/docs/6.0/forms/radio/

radioList()

public function radioList(mixed[] $items, mixed[] $options = []): static

Renders a list of radios, see Html::radioList().

Parameters

Parameter	Type	Description
`$items`	`mixed[]`	Data items, value => label.
`$options`	`mixed[]`	List options; `inline` defaults to `$inline`.

Returns

static

rangeInput()

public function rangeInput(mixed[] $options = []): static

Renders a range input wrapped in the .form-range element and registers the plugin bundle that initializes it.

The rangeOptions option holds the HTML attributes of the wrapper, for example data-bs-bubble or a theme class.

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Input attributes, for example `min`, `max`, `step`, or `list`.

Returns

static

See also

https://getbootstrap.com/docs/6.0/forms/range/

render()

public function render(callable(): mixed|string|null $content = null): string

Parameters

Parameter	Type	Description
`$content`	`callable(): mixed\|string\|null`	Field content, or `null` to render the parts with `$template`.

Returns

string

staticControl()

public function staticControl(mixed[] $options = []): static

Renders a read-only plain-text control with the attribute value.

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Tag attributes; the `value` option replaces the attribute value.

Returns

static

See also

https://getbootstrap.com/docs/6.0/forms/form-control/#readonly-plain-text

textarea()

public function textarea(mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Tag attributes merged over `$inputOptions`.

Returns

static

textInput()

public function textInput(mixed[] $options = []): static

Parameters

Parameter	Type	Description
`$options`	`mixed[]`	Tag attributes merged over `$inputOptions`.

Returns

static

public function widget(string $class, mixed[] $config = []): static

Parameters

Parameter	Type	Description
`$class`	`string`	Widget class name.
`$config`	`mixed[]`	Widget configuration.

Returns

static

createLayoutConfig()

protected function createLayoutConfig(mixed[] $instanceConfig): array<string, mixed>

Returns the layout-specific default configuration.

Defaults are taken from the current property values, so subclasses can redefine them.

Parameters

Parameter	Type	Description
`$instanceConfig`	`mixed[]`	Configuration passed to the constructor.

Returns

array<string, mixed>: Configuration merged under the constructor configuration.

horizontalCssClass()

protected function horizontalCssClass(string $key): mixed[]|string

Returns a grid class of $horizontalCssClasses, or an empty array when it is unset or empty.

Parameters

Parameter	Type	Description
`$key`	`string`

Returns

mixed[]|string

layout()

protected function layout(): string

Returns the layout of the owning form, or ActiveForm::LAYOUT_DEFAULT for a non-Bootstrap form.

Returns

string

registerFloatingFeedbackStyle()

protected function registerFloatingFeedbackStyle(): void

Registers, once per form, the style rule that displays the feedback following a .form-floating wrapper when its control or its container carries the error CSS class. Whitespace-separated classes in ActiveForm::$errorCssClass are matched together; no rule is registered when it holds no class.

The form id and each class are escaped through Html::escapeCssIdentifier(); the registration key keeps the raw id.

See also

https://developer.mozilla.org/en-US/docs/Web/CSS/:has

renderBooleanInput()

protected function renderBooleanInput(string $type, mixed[] $options, bool $enclosedByLabel): void

Renders a checkbox or radio with the layout-specific template and label.

Parameters

Parameter	Type	Description
`$type`	`string`	Input type, either `checkbox` or `radio`.
`$options`	`mixed[]`	Input attributes and the special options of `checkbox()`.
`$enclosedByLabel`	`bool`	Whether to render the input inside the label.

renderLabelParts()

protected function renderLabelParts(string|null $label = null, mixed[] $options = []): void

Renders the {beginLabel}, {labelTitle}, and {endLabel} parts.

Parameters

Parameter	Type	Description
`$label`	`string\|null`	Label content, or `null` for the `label` option or the encoded model label.
`$options`	`mixed[]`	Tag attributes merged over `$labelOptions`.

renderListInput()

protected function renderListInput(string $type, mixed[] $items, mixed[] $options): void

Renders a checkbox or radio list with the list label pointing to no control.

In the floating layout the list cannot float, so it uses the stacked template and a .form-label label.

Parameters

Parameter	Type	Description
`$type`	`string`	Input type, either `checkbox` or `radio`.
`$items`	`mixed[]`	Data items, value => label.
`$options`	`mixed[]`	List options.

renderWrapperParts()

protected function renderWrapperParts(): void

Builds the {beginWrapper} and {endWrapper} parts unless they are already set.

In the floating layout the wrapper receives the error CSS class, so the sibling feedback is displayed.

ActiveField

Properties

Methods

Method details

__construct()

checkbox()

checkboxList()

colorInput()

dropDownList()

error()

fileInput()

hint()

inline()

input()

label()

listBox()

passwordInput()

radio()

radioList()

rangeInput()

render()

staticControl()

textarea()

textInput()

widget()

createLayoutConfig()

horizontalCssClass()

layout()

registerFloatingFeedbackStyle()

renderBooleanInput()

renderLabelParts()

renderListInput()

renderWrapperParts()