yii2: make checkbox to be checked

yii2: make checkbox to be checked

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why selected Appears Instead of checked in Yii2 Checkboxes

When rendering a checkbox field using ActiveForm, it is common to expect the HTML attribute checked when the model value matches the input value. However, developers often observe that Yii2 generates the attribute selected instead. This behavior stems from how the framework handles boolean attributes and HTML5 standards, rather than an implementation bug or a configuration oversight.

The Mechanics of Boolean Attributes in HTML5

In standard HTML4, boolean attributes like checked, disabled, or readonly were typically rendered explicitly as <input type="checkbox" checked>. In this syntax, the presence of the word indicated the state.

HTML5 introduced a significant shift to improve developer experience and reduce code verbosity. Under HTML5 specifications, a boolean attribute is considered "present" if it appears with no value or with the name of the attribute as its value. Consequently, <input checked> and <input checked="checked"> are functionally identical in behavior.

Furthermore, HTML5 introduced a new set of attributes for form elements to represent their state: selected, readonly, and disabled. While checked remains valid for checkboxes, the framework's renderer prioritizes these newer semantic attributes when available. When you pass a truthy value to the checkbox helper, Yii2 interprets this as "the input should be in an active state." It then applies the attribute selected to signal this state to the browser.

Analyzing the Active Field Helper Behavior

When using $form->field($model, 'order')->checkBox([...]), you are invoking a specific helper method that generates an input element. The configuration array allows you to manipulate the output via the checked and selected keys.

If you attempt to force the attribute by setting 'checked' => true, the underlying rendering logic likely sees this as a request to enable the field. Because the framework maps "enabled" states to the selected attribute for consistency with HTML5 norms, your custom configuration is overridden in favor of the standard boolean representation.

Similarly, attempting to set 'checked' => 'checked' results in the same outcome: the renderer normalizes the input to use selected. This normalization happens regardless of whether you pass a string or a boolean value for the property name. The framework prioritizes semantic correctness over explicit string matching for these specific attributes.

Achieving Explicit Output with uncheck

To generate an HTML string that explicitly includes the checked attribute rather than selected, you must leverage the uncheck configuration option available in the checkBox helper. By setting uncheck to null and ensuring the field is checked, the renderer logic changes slightly to accommodate your specific requirement for the legacy attribute name.

Consider the following implementation:

echo $form->field($model, 'order')
    ->checkBox([
        'label' => 'Enable Queue',
        'uncheck' => null,
        'checked' => true 
    ])

While this often results in selected, specific versions of the framework or custom renderers might handle the uncheck property differently when combined with an explicit check state. If the standard helper consistently outputs selected regardless of input, you may need to bypass the helper entirely to guarantee the attribute name.

Bypassing the Helper for Attribute Control

If your frontend validation, CSS selectors, or JavaScript logic strictly requires the presence of the string checked in the DOM source (which is rare but possible), the most reliable approach is to render the input element manually using Html::activeCheckbox. This method allows you to pass raw options that directly influence the generated HTML without interference from helper-level normalization.

echo Html::activeCheckbox(
    $model, 
    'order', 
    [
        'value' => 1,
        'name' => 'Queue[order]',
        'checked' => true,
        'id' => 'queue-order'
    ]
);

By using Html::activeCheckbox, you are calling the base widget logic directly. You can then inspect the generated output to see if it respects the checked attribute or if it defaults to selected. In many cases, simply ensuring that the model's property value matches the input value (e.g., $model->order == 1) is sufficient for the framework to render the correct state, regardless of the attribute name used.

Practical Implications and Compatibility

It is crucial to understand that the difference between checked and selected is purely syntactic. Browsers treat them identically; both result in a checked box visually. If your application relies on client-side scripts checking for document.getElementById('queue-order').getAttribute('checked'), these scripts will fail if the attribute is named selected.

To handle such edge cases, you can normalize the input value after rendering or adjust your JavaScript to check the state via the .checked property of the element rather than relying on the attribute name. However, if strict HTML source output is mandated by a third-party system that parses the raw DOM string, manual rendering via Html::activeCheckbox with explicit options provides the necessary control to force the desired attribute representation.

Our network