Better Field Descriptions
Allows users to add customizable, themeable descriptions to form fields across all entity types without requiring field management permissions.
better_field_descriptions
Install
composer require 'drupal/better_field_descriptions:^2.0'
composer require 'drupal/better_field_descriptions:8.x-1.7'
Overview
Better Field Descriptions provides a powerful solution for adding custom, themeable help text to form fields in Drupal. Unlike standard field descriptions that require field management permissions to edit, this module separates the concerns: site administrators can select which fields should have better descriptions, while content managers or editors can write and manage the description text themselves.
The module supports all entity types (nodes, taxonomy terms, users, etc.) and works with any field type. Descriptions can be positioned above the field, below the field, or between the field label and input element. Each description can have its own label, or use a site-wide default label.
Descriptions are rendered through Twig templates, providing full theming flexibility. The module includes two built-in templates: a simple text display and a collapsible fieldset wrapper. Developers can create custom templates that will be automatically discovered and made available in the configuration.
Features
- Add custom descriptions to any field on any entity type (nodes, taxonomy terms, users, media, etc.)
- Position descriptions above the field, below the field, or between the title and input element
- Assign custom labels to each description or use a global default label
- Fully themeable output via Twig templates with two built-in options: plain text and collapsible fieldset
- Separate permissions for field selection (admin) and description authoring (content managers)
- Works with all field types including file uploads, text areas, entity references, and more
- Automatically handles pseudo-fields like the title field
- Template auto-discovery: custom templates placed in theme folder are automatically available
- Required field indicator support in description templates
Use Cases
Client-Friendly Field Help Text
A web agency builds a Drupal site for a client. The client wants to customize field descriptions to match their editorial guidelines, but the agency doesn't want to give them access to field configuration. With Better Field Descriptions, the agency selects the fields on the Settings tab, then gives the client the 'Add Better Descriptions To Selected Fields' permission. The client can now write their own help text without risking accidental field configuration changes.
Contextual Help in Complex Content Types
A site has content types with many fields where content authors need guidance. Using the 'Between title and input' position option, administrators can place detailed instructions directly beneath each field label but above the input, making the help text more prominent than standard Drupal field descriptions which appear below the input.
Collapsible Help Documentation
For fields requiring extensive documentation (acceptable formats, guidelines, examples), use the fieldset template to wrap descriptions in a collapsible element. This keeps forms clean while making detailed help available on demand.
Consistent Labeling Across Forms
Set a default label like 'Guidelines' or 'Help' that applies to all descriptions, creating a consistent UI pattern across the site. Override with custom labels for specific fields when needed.
Moving Existing Descriptions
Sometimes the default description position (below the input) is not ideal. By enabling a field for better descriptions but leaving the description text empty, the module will use the original field description but allow you to reposition it above the field or between the label and input.
Custom Template for Branding
Create a custom template file (e.g., better-field-descriptions-branded.html.twig) in your theme's templates folder. The module auto-discovers it and makes it available in the template dropdown. Use this to style descriptions with your site's design system, icons, or specific markup requirements.
Tips
- Always enable entity types on the Entities tab first, then select fields on Settings, then add descriptions on Bundles - the tabs must be used in this order
- The 'Between title and input' position can cause duplicate labels with some field types - always review your forms after saving
- Leave the description field empty to reposition the original field description without changing its text
- Custom templates in your theme's templates folder are auto-discovered - name them better-field-descriptions-*.html.twig
- Users need both the module permission AND 'Use the administration pages and help' permission to access the configuration pages
- Template changes trigger a theme registry rebuild which may briefly impact site performance
- For file/image fields, the module automatically adjusts prefix/suffix positions to work correctly with the managed_file widget
Technical Details
Admin Pages 3
/admin/config/content/better_field_descriptions
The main settings page where administrators select which fields across all configured entity types and bundles should have better descriptions enabled. Fields are organized by entity type and bundle in collapsible sections. Checking a field here makes it available for description editing on the Bundles tab.
/admin/config/content/better_field_descriptions/bundles
The description editing page where users with the appropriate permission can write and configure the actual description text for each enabled field. This is where content managers add helpful guidance for content authors.
/admin/config/content/better_field_descriptions/entities
Configuration page to select which entity types should be available for better field descriptions. Only entity types enabled here will appear on the main Settings page for field selection.
Permissions 2
Hooks 3
hook_field_widget_form_alter
The module implements this hook to inject better descriptions into field widgets during form rendering. It checks if the current field has a better description configured, then adds the rendered description to the appropriate position in the form element.
hook_theme
Registers the better_field_descriptions theme hook with configurable template file and path. Allows custom templates to be discovered from the active theme.
hook_help
Provides help text for the module's help page at /admin/help/better_field_descriptions.