Menu Item Extras
Provides extra fields for Menu Items using Drupal core's Menu Link Content entity without requiring additional entities.
menu_item_extras
Install
composer require 'drupal/menu_item_extras:^3.1'
composer require 'drupal/menu_item_extras:^3.0'
Overview
Menu Item Extras extends Drupal's core menu system by enabling the addition of custom fields to menu items. Unlike Mega Menu solutions that rely on separate entities, this module leverages the built-in Menu Link Content entity, treating each menu as a bundle. This approach allows site builders to add any field type (text, image, taxonomy references, etc.) directly to menu items through the standard Field UI interface.
The module introduces per-item view mode support, enabling different display configurations for individual menu links. It also provides enhanced template suggestions based on menu name, menu level, and view mode, giving theme developers granular control over menu item rendering.
Key technical aspects include automatic entity type modification where menus become bundles of menu_link_content entities, a "Children" pseudo-field for controlling submenu placement in the display, and a custom cache context for active trail-aware menu rendering.
Features
- Enables custom fields on menu items using Drupal's Field UI (text, images, entity references, etc.)
- Per-item view mode selection allowing different display configurations for individual menu items
- Menu-specific bundling where each menu acts as a bundle for menu_link_content entities
- Enhanced template suggestions based on menu name, menu level, view mode, and region placement
- Children pseudo-field to control submenu item positioning within parent menu item display
- Views integration with custom argument default plugin for active menu item ID
- Drush command support for clearing menu extra data
- Uninstall validation to prevent orphaned data
- Active trail-aware cache context for optimized menu rendering
- Configuration export handling that automatically adds module dependencies
Use Cases
Mega Menu with Rich Content
Create a mega menu by adding image, body text, and taxonomy reference fields to your main navigation menu. Use the view mode feature to display different content at different menu levels - for example, show featured images on top-level items and text descriptions on child items.
Per-Item Promotional Banners
Add a promotional banner image field to menu items. Use view mode settings to display the banner only for specific menu items designated as featured, while other items display normally.
Categorized Navigation with Related Content
Add entity reference fields to menu items pointing to content or taxonomy terms. Display related products, articles, or categories directly within the dropdown menu without creating separate mega menu blocks.
Regional Menu Styling
Use the region-based template suggestions (menu--extras--main--header.html.twig vs menu--extras--main--footer.html.twig) to display the same menu differently in header versus footer regions.
Contextual Views Based on Menu Position
Use the Views argument default plugin to create blocks that display content related to the currently active menu item, enabling dynamic sidebars or content areas that change based on navigation context.
Tips
- Use the 'Children' pseudo-field in Manage display to control where submenu items appear relative to the parent item's custom fields
- Create custom view modes for menu_link_content entity to have different displays for featured vs regular menu items
- Access the menu item entity in templates via {{ item.entity }} to conditionally display based on field values: {% if item.entity.field_featured.value == '1' %}
- Template suggestions include menu level, allowing different markup for first-level vs deeper navigation: menu-link-content--main--menu-level-0--default.html.twig
- The module automatically adds proper cache contexts, but complex custom implementations may need to account for the menu_item_extras_link_item_content_active_trails cache context
Technical Details
Admin Pages 4
/admin/structure/menu/manage/{menu}
Standard menu edit form enhanced with a 'Clear related data' button that removes all extra field data (view_mode values) from menu items. This is useful before uninstalling the module or resetting menu customizations.
/admin/structure/menu/manage/{menu}/view_modes_settings/default
Provides a tabular interface to assign view modes to each menu item in bulk. Displays all menu links in a tree structure with a view mode selector dropdown for each item, allowing quick configuration without editing individual menu items.
/admin/structure/menu/manage/{menu}/clear
Confirmation form that appears when clicking 'Clear related data' on the menu edit page. Confirms deletion of extra data (view_mode field values) for all items in the specified menu.
/admin/modules/uninstall/extra_data/menu_item_extras
Administrative action route accessible during module uninstall. Clears all extra data from all menus to allow clean module uninstallation.
Hooks 10
hook_entity_type_build
Modifies the menu_link_content entity to use menus as bundles and sets custom handlers for views data, forms, and link templates.
hook_entity_base_field_info
Adds the 'view_mode' base field to menu_link_content entities for per-item view mode selection.
hook_theme
Defines theme hooks for menu__extras, menu_link_content, and menu_levels templates.
hook_preprocess_block
Modifies menu blocks to use the base 'menu' theme and passes region data for template suggestions.
hook_theme_suggestions_menu_link_content
Provides template suggestions for menu link content based on view mode, menu name, menu level, and entity ID.
hook_theme_suggestions_menu_levels
Provides template suggestions for menu levels based on menu name and level.
hook_theme_suggestions_menu
Adds suggestions for menus with extra fields including region-based suggestions.
hook_preprocess_menu
Processes menu trees for menus with extra fields, adding rendered content to each item.
hook_entity_extra_field_info
Creates 'children' pseudo-field for controlling submenu position in menu item display.
hook_entity_view_alter
Hides default menu link fields (title, description, weight, expanded, enabled) from render output.
Drush Commands 1
drush menu-item-extras-clear-extra-data
Clears menu related extra data (view_mode field values) for a specific menu or all menus.
Troubleshooting 5
Navigate to any menu's edit page and click 'Clear related data', or use the link provided in the uninstall validation message at /admin/modules/uninstall/extra_data/menu_item_extras. You can also use Drush: drush mie:clear_data all
Ensure you've added fields via Structure > Menus > [Menu Name] > Manage fields. Also verify the fields are enabled in 'Manage form display' for the menu bundle.
Check 'Manage display' settings for the menu bundle and ensure fields are not hidden. Also verify you're using a template that outputs {{ content }} or the specific field values.
Ensure proper template naming: menu--extras--[menu-name].html.twig for menu level, menu-link-content--[menu-name]--[view-mode].html.twig for items. Clear caches after adding templates.
When a menu item is moved to a different menu, its custom field data is cleared (by design) since fields are bundle-specific. Re-enter the field data after moving.
Security Notes 3
- The module uses Drupal's core permission system - 'administer menu' permission is required for all administrative operations including clearing data
- Field values should be properly escaped when used in custom templates using Twig's auto-escaping or explicit |escape filter
- When exposing menu fields via REST or JSON:API, review field access settings as the module does not provide out-of-box REST support