How to add class to ActiveForm in Yii 2.0 framework?

How to add class to ActiveForm in Yii 2.0 framework?

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

Stefan Bogdanescu

Founder & Senior Architect

Applying CSS Classes to ActiveForm in Yii 2.0

You want your login form to render as a <form> tag with a specific class="userform" attribute and a nested layout involving grid containers like .ui-grid-solo. In raw HTML, this is trivial, but Yii 2.0's ActiveForm widget abstracts the generation of these tags. To achieve the desired output without stripping your custom classes, you need to explicitly configure the form properties or use the contentWrapper property if you are wrapping the fields in a specific container.

The most direct way to assign a class to the generated <form> tag is via the config options passed to the ActiveForm widget instantiation. You should look for the options property within the configuration array. This property accepts an associative array that maps directly to HTML attributes of the form element itself.

Here is how you structure the widget call:

<?= ActiveForm::begin([
    'id' => 'login-form',
    'action' => '/login',
    'method' => 'post',
    'options' => [
        'class' => 'userform',
        'role' => 'form',
    ],
]) ?>

    <!-- Your form fields go here -->

<?= ActiveForm::end() ?>

In this example, the options key inside the configuration array is responsible for injecting the attributes. By setting 'class' => 'userform', Yii will output <form class="userform" ...> exactly as requested. You can also include other attributes like role="form" in the same array if your CSS framework relies on it.

Now, let's address the nested structure you provided:

<div class="ui-grid-solo">
    <div class="ui-grid-a">
        <!-- inputs -->
    </div>
</div>

By default, ActiveForm generates its fields inside a <div> wrapper with the class form-fieldset-wrapper (or similar depending on your theme). If you want to replace this default wrapper with your own .ui-grid-solo container, you must use the contentWrapper property. This property allows you to define a custom HTML string that will be rendered around the form fields.

<?= ActiveForm::begin([
    'options' => [
        'class' => 'userform',
    ],
    'contentWrapper' => '<div class="ui-grid-solo"><div class="ui-grid-a">',
]) ?>

    <?= $form->field($model, 'login')->textInput(['id' => 'login', 'data-clear-btn' => 'true']) ?>
    <?= $form->field($model, 'password')->passwordInput(['id' => 'password', 'autocomplete' => 'off']) ?>
    
    <!-- Checkbox field -->
    <div class="ui-grid-a">
        <?= $form->field($model, 'remind')->checkbox() ?>
        <label for="<?= $form->field($model, 'remind')->id ?>"><?= $form->field($model, 'remind')->label(false) ?></label>
    </div>

<?= ActiveForm::end() ?>

Note the complexity in the last example. When using contentWrapper, you are essentially taking manual control of the HTML structure. The widget expects to close the wrapper at the end, but if you nest your own divs inside the contentWrapper string, you must ensure the closing tags match your opening tags perfectly. In the snippet above, I manually closed the grid containers after the form ends or ensured the structure aligns with how ActiveForm::end() renders its closing tag (which usually wraps everything in a final container).

A common pitfall here is forgetting that ActiveForm::begin() opens the wrapper and ActiveForm::end() closes it. If you set contentWrapper to include opening tags for your grid, you must ensure those closing tags are either inside the string or handled by the widget's default behavior. Often, it is cleaner to let ActiveForm handle the outermost container and only inject your specific classes via the options['class'] if the framework supports it, but for complex grid layouts, manual contentWrapper strings are necessary.

Another consideration is the submit button. In your HTML snippet, you had an onclick handler attached to the submit input:

<input type="submit" value="Login" onclick="this.form.submit();">

In Yii 2.0, it is best practice to avoid inline JavaScript for form submission. The widget automatically generates a hidden _csrf token field and ensures the form submits correctly upon clicking the button defined by ActiveForm::field(). You can customize the submit button's label and options using:

<?= $form->field($model, 'submit')->textInput(['value' => 'Login', 'type' => 'submit']) ?>

Or simply rely on the default submit field provided by the widget, which respects any CSS classes you might add to it via the submitButtonOptions property if needed.

If you are building this for a project that requires specific UI grid behaviors, ensure your CSS framework (like jQuery Mobile or similar) is loaded before the form renders. The attributes like data-clear-btn="true" and data-mini="true" in your input fields suggest a mobile-first approach; Yii respects standard HTML5 attributes, so passing them in the field configuration array works seamlessly without modification.

For more advanced layout requirements where the default widget structure is too restrictive, consider creating a custom form widget or extending ActiveForm. However, for most cases involving simple class additions and grid wrappers, manipulating options and contentWrapper as shown above provides the flexibility you need without over-engineering the solution.

Our network