Form Labels
Every form input needs a label. Use to create accessible, clickable labels that are correctly associated with their inputs.
Basic Usage and Signature
function form_label(string $label_text, array $attributes = []): stringNote on Association: To explicitly associate a label with an input, you must pass the for attribute inside the $attributes array. The value of for must match the id of the target input.
Parameters
| Parameter | Type | Description |
|---|---|---|
$label_text |
string | The text or HTML content displayed inside the label. **Not automatically escaped.** |
$attributes |
array | (optional) An associative array of HTML attributes (e.g., class, id, for). Defaults to []. |
Return Value
| Type | Description |
|---|---|
| string | The generated HTML label element. |
Example 1: Simple Label (Implicit Association)
While valid, this method relies on the input being nested or immediately following the label.
echo form_label('Username');
echo form_input('username', $username);
// Output: <label>Username</label><input name="username" value="[...]" />Example 2: Explicit Association (Best Practice)
This is the recommended approach for accessibility. The for attribute links the label to the input via the input's id.
$input_id = 'email-field';
$label_attrs = ['for' => $input_id];
echo form_label('Email Address', $label_attrs);
echo form_email('email', $email, ['id' => $input_id]);
// Clicking the label will focus the input field.Example 3: With Additional Attributes
$input_id = 'name-field';
$label_attrs = [
'for' => $input_id,
'class' => 'form-label required',
'data-tooltip' => 'Enter your full name'
];
echo form_label('Full Name', $label_attrs);
echo form_input('full_name', $full_name, ['id' => $input_id]);Checkbox and Radio Labels
Explicit association is particularly important for non-standard inputs like checkboxes and radios to make their text areas clickable.
// Option 1: Wrap input in label (Valid HTML)
echo '<label>';
echo form_checkbox('subscribe', 1, $subscribe);
echo ' Subscribe to newsletter';
echo '</label>';
// Option 2: Use the 'for' attribute (Recommended for external styling)
echo form_label('Agree to terms', ['for' => 'terms-checkbox']);
echo form_checkbox('terms', 1, $terms, ['id' => 'terms-checkbox']);Form Structure Pattern
It is best practice to wrap label/input pairs in a container for consistent layout and styling.
echo form_open('users/submit');
echo '<div class="form-group">';
echo form_label('Full Name', ['for' => 'name-field']);
echo form_input('full_name', $full_name, ['id' => 'name-field']);
echo '</div>';
echo '<div class="form-group">';
echo form_label('Email', ['for' => 'email-field']);
echo form_email('email', $email, ['id' => 'email-field']);
echo '</div>';
echo form_submit('submit', 'Save');
echo form_close();Required Field Indicators
Since $label_text is not escaped, you can safely include HTML for styling required field indicators.
echo form_label('Email Address <span class="required-indicator">*</span>', ['for' => 'email-field']);
echo form_email('email', $email, ['id' => 'email-field']);Why Labels Matter
- **Accessibility**: Screen readers announce the label for the associated input.
- **Usability**: Clicking the label text focuses the input field, increasing the clickable target area.
- **Clarity**: Users immediately understand the purpose of the adjacent input.
Security Warning: The $label_text is not automatically HTML-escaped. If this value comes from user input (e.g., a database record name), you must manually sanitize it before outputting it.
Use the built-in helper function to safely escape data for HTML output:
$user_defined_label = "Name <script>alert('xss');</script>";
$safe_label = out($user_defined_label);
echo form_label($safe_label, ['for' => 'field-id']);Always use labels and explicitly associate them with the for attribute. They are required for WCAG accessibility compliance and significantly improve usability.
We're continually improving the Trongate documentation. If anything is incorrect, unclear, incomplete, or could be better, we'd genuinely appreciate your input.
Share your thoughts in the Documentation Feedback.