Field Group
Provides the ability to group fields on both form and display modes for all fieldable entities.
field_group
Install
composer require 'drupal/field_group:^4.0'
composer require 'drupal/field_group:8.x-3.6'
composer require 'drupal/field_group:8.x-3.3'
Overview
Field Group is a powerful module that enables you to organize and group fields on entity form and view displays. It works with all fieldable entities in Drupal, including content types, users, taxonomy terms, and any custom entities.
The module uses a plugin-based architecture that allows unlimited nesting of field groups and provides multiple formatter types including fieldsets, details (collapsible), tabs (horizontal and vertical), HTML elements, and more. Each formatter has its own configuration options for customizing appearance and behavior.
Field groups are configured through the same interface as field display management, making it intuitive to organize fields into logical groups. Groups can contain fields, other groups, or extra fields provided by other modules, enabling complex multi-level layouts.
Features
- Group fields on entity form displays (add/edit forms) with customizable formatters
- Group fields on entity view displays (content view pages) with customizable formatters
- Support for unlimited nesting of field groups within other field groups
- Multiple built-in formatter types: Fieldset, Details, Details Sidebar, Tabs (horizontal/vertical), Tab, and HTML Element
- Plugin-based architecture allowing custom formatters to be created by other modules
- Collapsible/expandable groups with open/closed default states
- Custom CSS classes and ID attributes for each group
- Responsive tabs with configurable width breakpoint for automatic disabling
- Mark groups as required when containing required fields (form context)
- Support for HTML in group labels with XSS filtering
- Integration with Field UI for seamless configuration experience
- Migration support from Drupal 6/7 field groups via contrib module
- Theme suggestions for customizing group appearance per entity type/bundle
Use Cases
Organizing Long Node Edit Forms
For content types with many fields, use field groups to organize related fields into logical sections. Create a Tabs group with horizontal direction, then add Tab groups for each section (e.g., 'Basic Info', 'SEO Settings', 'Advanced Options'). Each tab contains related fields, making the form more manageable for content editors.
Creating Collapsible Configuration Sections
Use Details formatter to create collapsible sections on edit forms. Set 'open' to FALSE for less-frequently used options to reduce visual clutter. For example, group advanced settings in a collapsed Details section so they're available but not distracting.
Sidebar Organization on Node Forms
Use Details Sidebar formatter to move groups to the entity form sidebar alongside publishing options. Useful for metadata fields, scheduling options, or other settings that don't need to be in the main content area.
Custom Styled Content Sections on Display
Use HTML Element formatter on view displays to wrap groups of fields in semantic HTML elements (section, article, aside) with custom CSS classes. This enables rich theming and layout control without template overrides.
Multi-step Style Forms
Create vertical tabs to simulate a multi-step form workflow. Each tab represents a logical step or category, guiding users through complex content entry while keeping all data on a single form submission.
Responsive Tab Layouts
Configure the Tabs formatter with a width_breakpoint setting to automatically disable tabs on mobile devices, converting them to a standard stacked layout for better mobile UX.
Tips
- Use meaningful group machine names as they appear in template suggestions (e.g., field-group--group-name.html.twig)
- Combine tabs with details inside them for two-level organization without deep nesting
- The 'Show empty fields' setting is useful for debugging but should typically be disabled in production
- Use the HTML Element formatter with semantic elements (section, article, aside) for better accessibility and SEO
- Set width_breakpoint on Tabs to ensure good mobile experience - tabs automatically convert to stacked layout below the breakpoint
- Groups can contain other groups for unlimited nesting, but keep UX in mind - deep nesting can confuse users
- Theme suggestions are generated based on entity type, bundle, view mode, and group name for granular theming control
Technical Details
Admin Pages 2
/admin/structure/types/manage/{bundle}/form-display/add-group
Add a new field group to the form display of a content type. This page uses a two-step form: first select the group type and name, then configure the formatter settings.
/admin/structure/types/manage/{bundle}/display/add-group
Add a new field group to the view display of a content type. Works identically to form display but for entity view pages.
Hooks 7
hook_field_group_pre_render
Pre-render the build of the field group element. Called before the group element is rendered.
hook_field_group_pre_render_alter
Alter the pre-rendered build of the field group element after the formatter has processed it.
hook_field_group_build_pre_render_alter
Alter the pre-rendered build of the entire entity view, allowing modification of all field groups.
hook_field_group_form_process
Process the field group element during form building. Allows adding Form API states or other modifications.
hook_field_group_form_process_alter
Alter the processed build of a specific field group during form processing.
hook_field_group_form_process_build_alter
Alter the complete form after all field groups have been processed. Allows global modifications.
hook_field_group_delete_field_group
React to the deletion of a field group. Allows cleanup of related data.
Troubleshooting 5
Ensure the field group is not in the 'Disabled' region. Drag it to the 'Content' region in the Manage form display or Manage display page. Also verify the field group contains at least one field or has 'Display element also when empty' enabled.
Tab formatters must be children of a Tabs formatter. Create a parent Tabs group first, then create Tab groups inside it. The Tab formatter alone will render as a details element if not properly nested.
Ensure the field_group/details_validation or field_group/tab_validation library is attached. These are automatically attached by the formatters when required_fields setting is enabled.
The accordion formatter requires the jquery_ui_accordion module and field_group_accordion submodule. Note that this is deprecated due to jQuery UI EOL. Consider migrating to tabs or details formatters.
After migration, field groups may have NULL region values. Run the field_group_post_update_0001 update or manually assign regions through the UI.
Security Notes 3
- HTML in group labels is filtered through Drupal's XSS filter (Xss::filterAdmin) when 'Allow HTML in label' is enabled
- Custom attributes entered in the HTML Element formatter are parsed and added safely through Drupal's Attribute class
- CSS class and ID inputs are validated to only allow letters, numbers, underscores, dashes, and spaces