# ActiveField

> ActiveField represents a form input field within an yii\widgets\ActiveForm.

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [widgets](/docs/api/yii/widgets/index.md) › ActiveField

| class | `yii\widgets\ActiveField` |
| --- | --- |
| Extends | [`yii\base\Component`](/docs/api/yii/base/component/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Since | 2.0 |
| Source | [`framework/widgets/ActiveField.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/widgets/ActiveField.php#L24) |

1 subclass:

- [`yii2\extensions\bootstrap6\ActiveField`](/docs/extensions/bootstrap6/reference/activefield/index.md)

ActiveField represents a form input field within an [`ActiveForm`](/docs/api/yii/widgets/activeform/index.md).

For more details and usage information on ActiveField, see the [guide article on forms](/docs/guide/input-forms/index.md).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-addAriaAttributes"></span>`$addAriaAttributes` | `bool` | Adds aria HTML attributes `aria-required` and `aria-invalid` for inputs Default: `true`. Available since 2.0.11. | `ActiveField` |
| <span id="property-attribute"></span>`$attribute` | `string` | The model attribute that this field is associated with. Default: `null`. | `ActiveField` |
| <span id="property-behaviors"></span>[`$behaviors`](/docs/api/yii/base/component/index.md#property-behaviors) read-only | `array<`[`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md)`<static>>` | List of behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`$enableAjaxValidation`](#property-enableAjaxValidation) | `bool\|null` | Whether to enable AJAX-based data validation. Default: `null`. | `ActiveField` |
| [`$enableClientValidation`](#property-enableClientValidation) | `bool\|null` | Whether to enable client-side data validation. Default: `null`. | `ActiveField` |
| [`$errorOptions`](#property-errorOptions) | `array` | The default options for the error tags. Default: `['class' => 'field-error']`. | `ActiveField` |
| <span id="property-form"></span>`$form` | [`ActiveForm`](/docs/api/yii/widgets/activeform/index.md) | The form that this field is associated with. Default: `null`. | `ActiveField` |
| [`$hintOptions`](#property-hintOptions) | `array` | The default options for the hint tags. Default: `['class' => 'hint-block']`. | `ActiveField` |
| [`$inputOptions`](#property-inputOptions) | `array` | The default options for the input tags. Default: `[]`. | `ActiveField` |
| [`$labelOptions`](#property-labelOptions) | `array` | The default options for the label tags. Default: `[]`. | `ActiveField` |
| <span id="property-model"></span>`$model` | [`yii\base\Model`](/docs/api/yii/base/model/index.md) | The data model that this field is associated with. Default: `null`. | `ActiveField` |
| [`$options`](#property-options) | `array` | The HTML attributes (name-value pairs) for the field container tag. Default: `[]`. | `ActiveField` |
| [`$parts`](#property-parts) | `array` | Different parts of the field (e.g. input, label). Default: `[]`. | `ActiveField` |
| [`$selectors`](#property-selectors) | `array` | The jQuery selectors for selecting the container, input and error tags. Default: `[]`. | `ActiveField` |
| [`$template`](#property-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}"`. | `ActiveField` |
| [`$validateOnBlur`](#property-validateOnBlur) | `bool\|null` | Whether to perform validation when the input field loses focus. Default: `null`. | `ActiveField` |
| [`$validateOnChange`](#property-validateOnChange) | `bool\|null` | Whether to perform validation when the value of the input field is changed. Default: `null`. | `ActiveField` |
| [`$validateOnType`](#property-validateOnType) | `bool\|null` | Whether to perform validation while the user is typing in the input field. Default: `null`. | `ActiveField` |
| [`$validationDelay`](#property-validationDelay) | `int\|null` | Number of milliseconds that the validation should be delayed when the user types in the field and [`$validateOnType`](/docs/api/yii/widgets/activefield/index.md#property-validateOnType) is set `true`. Default: `null`. | `ActiveField` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/component/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__clone"></span>[`__clone()`](/docs/api/yii/base/component/index.md#method-__clone) | This method is called after the object is created by cloning an existing one. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/component/index.md#method-__get) | Returns the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/component/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/component/index.md#method-__set) | Sets the value of a component property. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`__toString()`](#method-__toString) | PHP magic method that returns the string representation of this object. | `ActiveField` |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/component/index.md#method-__unset) | Sets a component property to be null. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehavior"></span>[`attachBehavior()`](/docs/api/yii/base/component/index.md#method-attachBehavior) | Attaches a behavior to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-attachBehaviors"></span>[`attachBehaviors()`](/docs/api/yii/base/component/index.md#method-attachBehaviors) | Attaches a list of behaviors to the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`begin()`](#method-begin) | Renders the opening tag of the field container. | `ActiveField` |
| <span id="method-behaviors"></span>[`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) | Returns a list of behaviors that this component should behave as. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/component/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/component/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`checkbox()`](#method-checkbox) | Renders a checkbox. | `ActiveField` |
| [`checkboxList()`](#method-checkboxList) | Renders a list of checkboxes. | `ActiveField` |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-detachBehavior"></span>[`detachBehavior()`](/docs/api/yii/base/component/index.md#method-detachBehavior) | Detaches a behavior from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-detachBehaviors"></span>[`detachBehaviors()`](/docs/api/yii/base/component/index.md#method-detachBehaviors) | Detaches all behaviors from the component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`dropDownList()`](#method-dropDownList) | Renders a drop-down list. | `ActiveField` |
| [`end()`](#method-end) | Renders the closing tag of the field container. | `ActiveField` |
| <span id="method-ensureBehaviors"></span>[`ensureBehaviors()`](/docs/api/yii/base/component/index.md#method-ensureBehaviors) | Makes sure that the behaviors declared in [`behaviors()`](/docs/api/yii/base/component/index.md#method-behaviors) are attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`error()`](#method-error) | Generates a tag that contains the first validation error of [`$attribute`](/docs/api/yii/widgets/activefield/index.md#property-attribute). | `ActiveField` |
| [`fileInput()`](#method-fileInput) | Renders a file input. | `ActiveField` |
| <span id="method-getBehavior"></span>[`getBehavior()`](/docs/api/yii/base/component/index.md#method-getBehavior) | Returns the named behavior object. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-getBehaviors"></span>[`getBehaviors()`](/docs/api/yii/base/component/index.md#method-getBehaviors) | Returns all behaviors attached to this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasEventHandlers"></span>[`hasEventHandlers()`](/docs/api/yii/base/component/index.md#method-hasEventHandlers) | Returns a value indicating whether there is any handler attached to the named event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/component/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/component/index.md#method-hasProperty) | Returns a value indicating whether a property is defined for this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`hiddenInput()`](#method-hiddenInput) | Renders a hidden input. | `ActiveField` |
| [`hint()`](#method-hint) | Renders the hint tag. | `ActiveField` |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`input()`](#method-input) | Renders an input tag. | `ActiveField` |
| [`label()`](#method-label) | Generates a label tag for [`$attribute`](/docs/api/yii/widgets/activefield/index.md#property-attribute). | `ActiveField` |
| [`listBox()`](#method-listBox) | Renders a list box. | `ActiveField` |
| <span id="method-off"></span>[`off()`](/docs/api/yii/base/component/index.md#method-off) | Detaches an existing event handler from this component. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| <span id="method-on"></span>[`on()`](/docs/api/yii/base/component/index.md#method-on) | Attaches an event handler to an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`passwordInput()`](#method-passwordInput) | Renders a password input. | `ActiveField` |
| [`radio()`](#method-radio) | Renders a radio button. | `ActiveField` |
| [`radioList()`](#method-radioList) | Renders a list of radio buttons. | `ActiveField` |
| [`render()`](#method-render) | Renders the whole field. | `ActiveField` |
| [`textarea()`](#method-textarea) | Renders a text area. | `ActiveField` |
| [`textInput()`](#method-textInput) | Renders a text input. | `ActiveField` |
| <span id="method-trigger"></span>[`trigger()`](/docs/api/yii/base/component/index.md#method-trigger) | Triggers an event. | [`yii\base\Component`](/docs/api/yii/base/component/index.md) |
| [`widget()`](#method-widget) | Renders a widget as the input of the field. | `ActiveField` |
| [`addAriaAttributes()`](#method-addAriaAttributes) protected | Adds aria attributes to the input options. | `ActiveField` |
| [`addErrorClassIfNeeded()`](#method-addErrorClassIfNeeded) protected | Adds validation class to the input options if needed. | `ActiveField` |
| [`addRoleAttributes()`](#method-addRoleAttributes) protected | Add role attributes to the input options | `ActiveField` |
| [`adjustLabelFor()`](#method-adjustLabelFor) protected | Adjusts the `for` attribute for the label based on the input options. | `ActiveField` |
| [`generateLabel()`](#method-generateLabel) protected | Generates the label element based on `labelOptions` configuration when `enclosedByLabel` is `false`. | `ActiveField` |
| [`getClientOptions()`](#method-getClientOptions) protected | Returns the JS options for the field. | `ActiveField` |
| [`getInputId()`](#method-getInputId) protected | Returns the HTML `id` of the input element of this form field. | `ActiveField` |
| [`isAjaxValidationEnabled()`](#method-isAjaxValidationEnabled) protected | Checks if ajax validation enabled for the field. | `ActiveField` |
| [`isClientValidationEnabled()`](#method-isClientValidationEnabled) protected | Checks if client validation enabled for the field. | `ActiveField` |

## Property details

### $enableAjaxValidation <span id="property-enableAjaxValidation"></span>

```php
public bool|null $enableAjaxValidation = null
```

Whether to enable AJAX-based data validation.

If not set, it will take the value of [`ActiveForm::$enableAjaxValidation`](/docs/api/yii/widgets/activeform/index.md#property-enableAjaxValidation).

### $enableClientValidation <span id="property-enableClientValidation"></span>

```php
public bool|null $enableClientValidation = null
```

Whether to enable client-side data validation.

If not set, it will take the value of [`ActiveForm::$enableClientValidation`](/docs/api/yii/widgets/activeform/index.md#property-enableClientValidation).

### $errorOptions <span id="property-errorOptions"></span>

```php
public array $errorOptions = ['class' => 'field-error']
```

The default options for the error tags.

The parameter passed to [`error()`](/docs/api/yii/widgets/activefield/index.md#method-error) will be
merged with this property when rendering the error tag.
The following special options are recognized:

- `tag`: the tag name of the container element. Defaults to `div`. Setting it to `false` will not render a container tag.
  See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag).
- `encode`: whether to encode the error output. Defaults to `true`.

If you set a custom `id` for the error element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly.

### $hintOptions <span id="property-hintOptions"></span>

```php
public array $hintOptions = ['class' => 'hint-block']
```

The default options for the hint tags.

The parameter passed to [`hint()`](/docs/api/yii/widgets/activefield/index.md#method-hint) will be
merged with this property when rendering the hint tag.
The following special options are recognized:

- `tag`: the tag name of the container element. Defaults to `div`. Setting it to `false` will not render a container tag.
  See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag).

### $inputOptions <span id="property-inputOptions"></span>

```php
public array $inputOptions = []
```

The default options for the input tags.

The parameter passed to individual input methods
(e.g. [`textInput()`](/docs/api/yii/widgets/activefield/index.md#method-textInput)) will be merged with this property when rendering the input tag.

If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly.

### $labelOptions <span id="property-labelOptions"></span>

```php
public array $labelOptions = []
```

The default options for the label tags.

The parameter passed to [`label()`](/docs/api/yii/widgets/activefield/index.md#method-label) will be
merged with this property when rendering the label tag.

### $options <span id="property-options"></span>

```php
public array $options = []
```

The HTML attributes (name-value pairs) for the field container tag.

The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode).
If a value is `null`, the corresponding attribute will not be rendered.
The following special options are recognized:

- `tag`: the tag name of the container element. Defaults to `div`. Setting it to `false` will not render a container tag.
  See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag).

If you set a custom `id` for the container element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly.

### $parts <span id="property-parts"></span>

```php
public array $parts = []
```

Different parts of the field (e.g. input, label).

This will be used together with
[`$template`](/docs/api/yii/widgets/activefield/index.md#property-template) to generate the final field HTML code. The keys are the token names in [`$template`](/docs/api/yii/widgets/activefield/index.md#property-template),
while the values are the corresponding HTML code. Valid tokens include `{input}`, `{label}` and `{error}`.
Note that you normally don't need to access this property directly as
it is maintained by various methods of this class.

### $selectors <span id="property-selectors"></span>

```php
public array $selectors = []
```

The jQuery selectors for selecting the container, input and error tags.

The array keys should be `container`, `input`, and/or `error`, and the array values
are the corresponding selectors. For example, `['input' => '#my-input']`.

The container selector is used under the context of the form, while the input and the error
selectors are used under the context of the container.

You normally do not need to set this property as the default selectors should work well for most cases.

### $template <span id="property-template"></span>

```php
public string $template = "{label}\n{input}\n{hint}\n{error}"
```

The template that is used to arrange the label, the input field, the error message and the hint text.

The following tokens will be replaced when [`render()`](/docs/api/yii/widgets/activefield/index.md#method-render) is called: `{label}`, `{input}`, `{error}` and `{hint}`.

### $validateOnBlur <span id="property-validateOnBlur"></span>

```php
public bool|null $validateOnBlur = null
```

Whether to perform validation when the input field loses focus.

If not set, it will take the value of [`ActiveForm::$validateOnBlur`](/docs/api/yii/widgets/activeform/index.md#property-validateOnBlur).

### $validateOnChange <span id="property-validateOnChange"></span>

```php
public bool|null $validateOnChange = null
```

Whether to perform validation when the value of the input field is changed.

If not set, it will take the value of [`ActiveForm::$validateOnChange`](/docs/api/yii/widgets/activeform/index.md#property-validateOnChange).

### $validateOnType <span id="property-validateOnType"></span>

```php
public bool|null $validateOnType = null
```

Whether to perform validation while the user is typing in the input field.

If not set, it will take the value of [`ActiveForm::$validateOnType`](/docs/api/yii/widgets/activeform/index.md#property-validateOnType).

### $validationDelay <span id="property-validationDelay"></span>

```php
public int|null $validationDelay = null
```

Number of milliseconds that the validation should be delayed when the user types in the field and [`$validateOnType`](/docs/api/yii/widgets/activefield/index.md#property-validateOnType) is set `true`.

If not set, it will take the value of [`ActiveForm::$validationDelay`](/docs/api/yii/widgets/activeform/index.md#property-validationDelay).

## Method details

### __toString() <span id="method-__toString"></span>

```php
public function __toString(): string
```

PHP magic method that returns the string representation of this object.

**Returns**

`string`: The string representation of this object.

### begin() <span id="method-begin"></span>

```php
public function begin(): string
```

Renders the opening tag of the field container.

**Returns**

`string`: The rendering result.

### checkbox() <span id="method-checkbox"></span>

```php
public function checkbox(array $options = [], bool $enclosedByLabel = true): $this
```

Renders a checkbox.

This method will generate the `checked` tag attribute according to the model attribute value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options in terms of name-value pairs. The following options are specially handled: - `uncheck`: string, the value associated with the uncheck state of the checkbox. 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\|false\|null`, 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 [encode](/docs/api/yii/helpers/basehtml/index.md#method-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. Supports a `tag` sub-option (`'label'`/`false`/custom tag) for flexible label rendering. The rest of the options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-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`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |
| `$enclosedByLabel` | `bool` | Whether to enclose the checkbox within the label. If `true`, the method will still use [`$template`](/docs/api/yii/widgets/activefield/index.md#property-template) to layout the checkbox and the error message except that the checkbox is enclosed by the label tag. |

**Returns**

`$this`: The field object itself.

### checkboxList() <span id="method-checkboxList"></span>

```php
public function checkboxList(array $items, array $options = []): $this
```

Renders a list of checkboxes.

A checkbox list allows multiple selection, like [`listBox()`](/docs/api/yii/widgets/activefield/index.md#method-listBox).
As a result, the corresponding submitted value is an array.
The selection of the checkbox list is taken from the value of the model attribute.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$items` | `array` | The data item used to generate the checkboxes. The array values are the labels, while the array keys are the corresponding checkbox values. |
| `$options` | `array` | Options (name => config) for the checkbox list. For the list of available options please refer to the `$options` parameter of [`Html::activeCheckboxList()`](/docs/api/yii/helpers/basehtml/index.md#method-activeCheckboxList). |

**Returns**

`$this`: The field object itself.

### dropDownList() <span id="method-dropDownList"></span>

```php
public function dropDownList(array $items, array $options = []): $this
```

Renders a drop-down list.

The selection of the drop-down list is taken from the value of the model attribute.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$items` | `array` | The option data items. The array keys are option values, and the array values are the corresponding option labels. The array can also be nested (i.e. some array values are arrays too). For each sub-array, an option group will be generated whose label is the key associated with the sub-array. If you have a list of data models, you may convert them into the format described above using [`ArrayHelper::map()`](/docs/api/yii/helpers/basearrayhelper/index.md#method-map). Note, the values and labels will be automatically HTML-encoded by this method, and the blank spaces in the labels will also be HTML-encoded. |
| `$options` | `array` | The tag options in terms of name-value pairs. For the list of available options please refer to the `$options` parameter of [`Html::activeDropDownList()`](/docs/api/yii/helpers/basehtml/index.md#method-activeDropDownList). If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### end() <span id="method-end"></span>

```php
public function end(): string
```

Renders the closing tag of the field container.

**Returns**

`string`: The rendering result.

### error() <span id="method-error"></span>

```php
public function error(array|false $options = []): $this
```

Generates a tag that contains the first validation error of [`$attribute`](/docs/api/yii/widgets/activefield/index.md#property-attribute).

Note that even if there is no validation error, this method will still return an empty error tag.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array\|false` | The tag options in terms of name-value pairs. It will be merged with [`$errorOptions`](/docs/api/yii/widgets/activefield/index.md#property-errorOptions). The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If this parameter is `false`, no error tag will be rendered. The following options are specially handled: - `tag`: this specifies the tag name. If not set, `div` will be used. See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag). If you set a custom `id` for the error element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

**See also**

- [`$errorOptions`](/docs/api/yii/widgets/activefield/index.md#property-errorOptions)

### fileInput() <span id="method-fileInput"></span>

```php
public function fileInput(array $options = []): $this
```

Renders a file input.

This method will generate the `name` and `value` tag attributes automatically for the model attribute
unless they are explicitly specified in `$options`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### hiddenInput() <span id="method-hiddenInput"></span>

```php
public function hiddenInput(array $options = []): $this
```

Renders a hidden input.

Note that this method is provided for completeness. In most cases because you do not need
to validate a hidden input, you should not need to use this method. Instead, you should
use [`Html::activeHiddenInput()`](/docs/api/yii/helpers/basehtml/index.md#method-activeHiddenInput).

This method will generate the `name` and `value` tag attributes automatically for the model attribute
unless they are explicitly specified in `$options`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### hint() <span id="method-hint"></span>

```php
public function hint(string|bool|null $content, array $options = []): $this
```

Renders the hint tag.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$content` | `string\|bool\|null` | The hint content. If `null`, the hint will be generated via [`Model::getAttributeHint()`](/docs/api/yii/base/model/index.md#method-getAttributeHint). If `false`, the generated field will not contain the hint part. Note that this will NOT be [encoded](/docs/api/yii/helpers/basehtml/index.md#method-encode). |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the hint tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). The following options are specially handled: - `tag`: this specifies the tag name. If not set, `div` will be used. See also [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag). |

**Returns**

`$this`: The field object itself.

### input() <span id="method-input"></span>

```php
public function input(string $type, array $options = []): $this
```

Renders an input tag.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$type` | `string` | The input type (e.g. `text`, `password`) |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### label() <span id="method-label"></span>

```php
public function label(string|null|false $label = null, array|null $options = []): $this
```

Generates a label tag for [`$attribute`](/docs/api/yii/widgets/activefield/index.md#property-attribute).

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$label` | `string\|null\|false` | The label to use. If `null`, the label will be generated via [`Model::getAttributeLabel()`](/docs/api/yii/base/model/index.md#method-getAttributeLabel). If `false`, the generated field will not contain the label part. Note that this will NOT be [encoded](/docs/api/yii/helpers/basehtml/index.md#method-encode). |
| `$options` | `array\|null` | The tag options in terms of name-value pairs. It will be merged with [`$labelOptions`](/docs/api/yii/widgets/activefield/index.md#property-labelOptions). The options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If a value is `null`, the corresponding attribute will not be rendered. The following special options are recognized: - `label`: `string\|false\|null`, the label text. Used as fallback when `$label` parameter is `null`. If set to `false`, the label will not be rendered. The `$label` parameter always takes precedence over this option. - `tag`: `string\|false`, the tag name for the label element. Defaults to `'label'`. If set to `false`, the label content is rendered without any wrapping tag. If set to `'label'`, [`Html::activeLabel()`](/docs/api/yii/helpers/basehtml/index.md#method-activeLabel) is used (default behavior). Any other string value (e.g. `'span'`, `'div'`, `'h3'`) will use [`Html::tag()`](/docs/api/yii/helpers/basehtml/index.md#method-tag) with that element. |

**Returns**

`$this`: The field object itself.

### listBox() <span id="method-listBox"></span>

```php
public function listBox(array $items, array $options = []): $this
```

Renders a list box.

The selection of the list box is taken from the value of the model attribute.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$items` | `array` | The option data items. The array keys are option values, and the array values are the corresponding option labels. The array can also be nested (i.e. some array values are arrays too). For each sub-array, an option group will be generated whose label is the key associated with the sub-array. If you have a list of data models, you may convert them into the format described above using [`ArrayHelper::map()`](/docs/api/yii/helpers/basearrayhelper/index.md#method-map). Note, the values and labels will be automatically HTML-encoded by this method, and the blank spaces in the labels will also be HTML-encoded. |
| `$options` | `array` | The tag options in terms of name-value pairs. For the list of available options please refer to the `$options` parameter of [`Html::activeListBox()`](/docs/api/yii/helpers/basehtml/index.md#method-activeListBox). If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### passwordInput() <span id="method-passwordInput"></span>

```php
public function passwordInput(array $options = []): $this
```

Renders a password input.

This method will generate the `name` and `value` tag attributes automatically for the model attribute
unless they are explicitly specified in `$options`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### radio() <span id="method-radio"></span>

```php
public function radio(array $options = [], bool $enclosedByLabel = true): $this
```

Renders a radio button.

This method will generate the `checked` tag attribute according to the model attribute value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options 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\|false\|null`, a label displayed next to the radio button. 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 [encode](/docs/api/yii/helpers/basehtml/index.md#method-encode) it to prevent XSS attacks. When this option is specified, the radio button 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. Supports a `tag` sub-option (`'label'`/`false`/custom tag) for flexible label rendering. The rest of the options will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-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`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |
| `$enclosedByLabel` | `bool` | Whether to enclose the radio within the label. If `true`, the method will still use [`$template`](/docs/api/yii/widgets/activefield/index.md#property-template) to layout the radio button and the error message except that the radio is enclosed by the label tag. |

**Returns**

`$this`: The field object itself.

### radioList() <span id="method-radioList"></span>

```php
public function radioList(array $items, array $options = []): $this
```

Renders a list of radio buttons.

A radio button list is like a checkbox list, except that it only allows single selection.
The selection of the radio buttons is taken from the value of the model attribute.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$items` | `array` | The data item used to generate the radio buttons. The array values are the labels, while the array keys are the corresponding radio values. |
| `$options` | `array` | Options (name => config) for the radio button list. For the list of available options please refer to the `$options` parameter of [`Html::activeRadioList()`](/docs/api/yii/helpers/basehtml/index.md#method-activeRadioList). |

**Returns**

`$this`: The field object itself.

### render() <span id="method-render"></span>

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

Renders the whole field.

This method will generate the label, error tag, input tag and hint tag (if any), and
assemble them into HTML according to [`$template`](/docs/api/yii/widgets/activefield/index.md#property-template).

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$content` | `string\|callable\|null` | The content within the field container. If `null` (not set), the default methods will be called to generate the label, error tag and input tag, and use them as the content. If a callable, it will be called to generate the content. The signature of the callable should be: function ($field) { return $html; } |

**Returns**

`string`: The rendering result.

### textarea() <span id="method-textarea"></span>

```php
public function textarea(array $options = []): $this
```

Renders a text area.

The model attribute value will be used as the content in the textarea.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). If you set a custom `id` for the textarea element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### textInput() <span id="method-textInput"></span>

```php
public function textInput(array $options = []): $this
```

Renders a text input.

This method will generate the `name` and `value` tag attributes automatically for the model attribute
unless they are explicitly specified in `$options`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The tag options in terms of name-value pairs. These will be rendered as the attributes of the resulting tag. The values will be HTML-encoded using [`Html::encode()`](/docs/api/yii/helpers/basehtml/index.md#method-encode). The following special options are recognized: - `maxlength`: int\|bool, when `maxlength` is set `true` and the model attribute is validated by a string validator, the `maxlength` option will take the value of [`StringValidator::$max`](/docs/api/yii/validators/stringvalidator/index.md#property-max). This is available since version 2.0.3. Note that if you set a custom `id` for the input element, you may need to adjust the value of [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly. |

**Returns**

`$this`: The field object itself.

### widget() <span id="method-widget"></span>

```php
public function widget(string $class, array $config = []): $this
```

Renders a widget as the input of the field.

Note that the widget must have both `model` and `attribute` properties. They will
be initialized with [`$model`](/docs/api/yii/widgets/activefield/index.md#property-model) and [`$attribute`](/docs/api/yii/widgets/activefield/index.md#property-attribute) of this field, respectively.

If you want to use a widget that does not have `model` and `attribute` properties,
please use [`render()`](/docs/api/yii/widgets/activefield/index.md#method-render) instead.

While widgets extending from [`Widget`](/docs/api/yii/base/widget/index.md) work with active field, it is preferred to use
[`InputWidget`](/docs/api/yii/widgets/inputwidget/index.md) as a base class.

For example to use the [`MaskedInput`](/docs/api/yii/widgets/maskedinput/index.md) widget to get some date input, you can use
the following code, assuming that `$form` is your [`ActiveForm`](/docs/api/yii/widgets/activeform/index.md) instance:

```
$form->field($model, 'date')->widget(\yii\widgets\MaskedInput::class, [
    'mask' => '99/99/9999',
]);
```

If you set a custom `id` for the input element, you may need to adjust the [`$selectors`](/docs/api/yii/widgets/activefield/index.md#property-selectors) accordingly.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$class` | `string` | The widget class name. |
| `$config` | `array` | Name-value pairs that will be used to initialize the widget. |

**Returns**

`$this`: The field object itself.

**Throws**

- [`Exception`](https://www.php.net/manual/en/class.exception.php)

### addAriaAttributes() <span id="method-addAriaAttributes"></span>

```php
protected function addAriaAttributes(mixed &$options): mixed
```

Adds aria attributes to the input options.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `mixed` | Array input options |

**Returns**

`mixed`

**Since**

2.0.11

### addErrorClassIfNeeded() <span id="method-addErrorClassIfNeeded"></span>

```php
protected function addErrorClassIfNeeded(mixed &$options): mixed
```

Adds validation class to the input options if needed.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `mixed` | Array input options |

**Returns**

`mixed`

**Since**

2.0.14

### addRoleAttributes() <span id="method-addRoleAttributes"></span>

```php
protected function addRoleAttributes(mixed &$options, string $role): mixed
```

Add role attributes to the input options

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `mixed` | Array input options |
| `$role` | `string` |  |

**Returns**

`mixed`

**Since**

2.0.16

### adjustLabelFor() <span id="method-adjustLabelFor"></span>

```php
protected function adjustLabelFor(array $options): mixed
```

Adjusts the `for` attribute for the label based on the input options.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The input options. |

**Returns**

`mixed`

### generateLabel() <span id="method-generateLabel"></span>

```php
protected function generateLabel(array $options): array
```

Generates the label element based on `labelOptions` configuration when `enclosedByLabel` is `false`.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$options` | `array` | The input options array |

**Returns**

`array`: The cleaned options array with `labelOptions` removed

### getClientOptions() <span id="method-getClientOptions"></span>

```php
protected function getClientOptions(): array
```

Returns the JS options for the field.

**Returns**

`array`: The JS options.

### getInputId() <span id="method-getInputId"></span>

```php
protected function getInputId(): string
```

Returns the HTML `id` of the input element of this form field.

**Returns**

`string`: The input id.

**Since**

2.0.7

### isAjaxValidationEnabled() <span id="method-isAjaxValidationEnabled"></span>

```php
protected function isAjaxValidationEnabled(): bool
```

Checks if ajax validation enabled for the field.

**Returns**

`bool`

**Since**

2.0.11

### isClientValidationEnabled() <span id="method-isClientValidationEnabled"></span>

```php
protected function isClientValidationEnabled(): bool
```

Checks if client validation enabled for the field.

**Returns**

`bool`

**Since**

2.0.11