Label Help
Adds help text directly below form field labels, positioning it between the label and the input element.
label_help
Install
composer require 'drupal/label_help:8.x-1.0'
Overview
The Label Help module provides a way to add help text to Drupal form fields that appears below the form label but above the form input element itself. This is different from Drupal's standard field description which appears below the form element.
This positioning is particularly useful for providing immediate context or instructions that users should see before interacting with a form field, rather than after they've already started entering data. The module works with all Field API field types through intelligent placement logic that handles various widget configurations including containers, fieldsets, details elements, checkboxes, radios, and multi-value fields.
Label Help integrates seamlessly with the Field UI, adding a simple textarea to field configuration where administrators can enter the help text. For developers, it also provides a custom #label_help Form API property for programmatic use and works with hook_form_alter() for modifying existing forms.
The module includes specialized templates and CSS for Drupal's major admin themes: Seven, Claro, and Gin, ensuring consistent and properly styled display across different administrative interfaces.
Features
- Adds 'Label help message' textarea to Field UI field configuration, allowing administrators to enter help text through the web interface
- Positions help text between the field label and the form input element, providing context before users interact with the field
- Supports all Field API field types including textfields, checkboxes, radios, select lists, entity references, dates, links, files, images, and more
- Provides specialized placement logic handling 18+ different widget configurations including containers, fieldsets, details elements, and multi-value fields
- Includes theme-specific templates and CSS for Seven, Claro, and Gin admin themes with proper styling inheritance
- Provides #label_help Form API property for adding help text programmatically in custom modules or themes
- Works with hook_form_alter() and hook_FORM_ID_alter() for modifying existing form fields
- Includes debug modes for troubleshooting placement issues, showing use case matching and Form API element dumps
- Complements Drupal's existing field description rather than replacing it - both can be used together
Use Cases
Providing immediate field context
Use label help to provide essential instructions that users need to see before they start entering data. For example, on a 'Phone Number' field, you might add label help text saying 'Enter number with country code, e.g., +1 555-123-4567' so users know the expected format immediately.
Explaining field requirements
Add label help to explain specific requirements or restrictions for a field that users should understand upfront. For instance, on a 'Username' field, label help could state 'Must be 3-20 characters, letters and numbers only' making requirements visible before input.
Supplementing complex fields
For multi-value or complex field widgets like entity references or address fields, use label help to provide an overview of what the field is collecting, while using the standard description below for detailed instructions or examples.
Programmatic form enhancement
In custom modules or themes, use the #label_help Form API property or hook_form_alter() to add context-specific help text to forms. This is useful for adding dynamic help text based on user roles, current content, or other conditions.
Content editor guidance
Help content editors understand the purpose and best practices for each field. For example, on a 'Meta Description' field, label help could say 'Summarize page content in 155-160 characters for search engines' providing SEO guidance right where it's needed.
Tips
- Keep label help text concise - it should provide quick context, not lengthy documentation
- Use label help for 'must know before input' information and standard descriptions for 'nice to know' details
- Both label help and standard field descriptions can be used together - they serve complementary purposes
- The module automatically detects the active admin theme and applies appropriate styling
- Debug mode displays checkmarks (✅) for successfully placed messages and shows the use case number for troubleshooting
Technical Details
Hooks 2
#label_help
A custom Form API property that can be added to form elements to display help text below the field label. This is the programmatic way to add label help text.
hook_form_alter() / hook_FORM_ID_alter()
Standard Drupal form alter hooks can be used to add #label_help to existing form fields defined by other modules.
Troubleshooting 3
Enable debug mode by adding $settings['label_help_debug'] = TRUE; in settings.php. Reload the form page to see debug output identifying the field widget type and use case matched by Label Help placement logic. If no use case is detected, you'll see a warning message.
Enable Form API element dump mode by adding $settings['label_help_debug_dump'] = TRUE; in settings.php. This uses Symfony's Variable Dumper to provide a drillable dump of the Form API element array. Note: this may prevent complete page rendering, which is expected behavior.
Ensure you are using one of the supported admin themes: Seven, Claro, or Gin. The module includes specialized CSS for these themes. For custom themes, you may need to add custom CSS targeting the .description--label-help or .form-item__description--label-help classes.