Customizing Radio List Templates in Yii 2
Achieving a specific visual layout for form elements often requires stepping outside default behaviors, and the radioList widget in Yii 2 is no exception. When the standard output doesn't match your design requirements, you naturally turn to the radioTemplate option. The goal here is clear: you want to structure the HTML so that a common header label sits above a series of individual radio buttons, each with custom iconography and text spacing.
The core issue in your initial attempt stems from how the radioList widget parses its template string. The default rendering logic expects specific placeholders like {input} and {label} to be placed exactly where the widget can inject them. However, if you wrap these placeholders inside an outer <div> or misplace them within nested labels that aren't explicitly handled by the widget's internal loop, the structure breaks down.
To fix this, you must construct a template string that mirrors the exact HTML structure you desire, ensuring every element has a corresponding placeholder. In your target HTML, you have a container input-wrap, a header label, and then individual signup-radio blocks. The widget's radioList component is responsible for generating the radio inputs and their associated labels based on the data array passed (e.g., [1 => 'Male', 0 => 'Female']).
Here is how you should structure the template:
<?= $form->field($model, 'gender')
->radioList(
[
'Male' => 1,
'Female' => 0
],
[
// Define the custom HTML structure per item
'template' => '<div class="signup-radio">
<label>
{input}
<i></i>
<span>{label}</span>
</label>
</div>'
]
) ?>
Notice the separation of concerns. The radioList method handles the iteration over your data array. Inside the configuration array, the template key dictates how each item is rendered. Crucially, you must use {input} for the <input type="radio"...> tag and {label} for the text content (or a wrapper containing it).
In your original code snippet, you attempted to put everything inside a single large radioTemplate option for field(), which is not the correct API surface. The RadioListField widget accepts a separate configuration array as the second argument to radioList(). Inside that array, you define the template string.
A common pitfall when using custom templates is forgetting to escape HTML entities if they appear in your data source, though simple strings like 'Male' are usually safe. Another consideration is the separator option. In your desired output, the items appear stacked vertically within a flex or block container rather than horizontally inline. The default radioList might try to render them inline unless you explicitly manage the CSS classes (like signup-radio) and ensure the parent container handles the layout.
If you require the header label (<label class="gender-head">Gender</label>) to appear outside the widget's loop entirely, you cannot generate it via the radioList template because that template only runs once per item in the data array. Instead, render the header manually above the field:
<div class="input-wrap">
<label class="gender-head">Gender</label>
<?= $form->field($model, 'gender')
->radioList(
['Male' => 1, 'Female' => 0],
[
'template' => '<div class="signup-radio"><label>{input}<i></i><span>{label}</span></label></div>'
]
) ?>
</div>
This approach ensures the header is static and not duplicated for every radio button, while the widget handles the dynamic inputs. Ensure your CSS classes match exactly what you intend to style, as misaligned class names are a frequent source of layout bugs in Bootstrap or custom grid systems. By isolating the structural logic into the template string and managing non-repeating elements outside the widget, you maintain clean separation between static layout markup and dynamic form data rendering.