Menu Link Attributes
Allows you to add custom HTML attributes to menu links, including both the anchor tag and the containing list item element.
menu_link_attributes
Install
composer require 'drupal/menu_link_attributes:8.x-1.6'
Overview
Menu Link Attributes is a Drupal module that enhances menu link management by allowing administrators to add custom HTML attributes to menu links. This is particularly useful for adding CSS classes, link targets, ARIA attributes, or any other custom HTML attributes to menu items without modifying code.
The module provides a flexible YAML-based configuration system where administrators can define which attributes should be available on menu link forms. Each attribute can be configured with a label, description, input type (textfield, select, checkboxes, radios, managed_file), and predefined options. The module supports both link-level attributes (applied to the <a> tag) and container-level attributes (applied to the wrapping <li> element).
By default, the module provides three commonly-used attributes: CSS classes for the link, CSS classes for the container, and link target. Administrators can easily add more attributes through the configuration page using YAML syntax.
Features
- Add custom HTML attributes to menu links through the menu item edit form
- Support for link attributes (applied to the <a> tag) and container attributes (applied to the <li> element)
- Flexible YAML-based configuration for defining available attributes
- Multiple input types supported: textfield, select, checkboxes, radios, and managed_file
- Default attributes included: link class, container class, and link target
- Permission-based access control for using and administering attributes
- Automatic handling of class attributes as arrays for proper HTML rendering
- Translation-aware attribute handling with proper multilingual support
- Integration with YAML Editor module for easier configuration editing
Use Cases
Adding CSS classes for styling menu items
Add custom CSS classes to menu links to style specific items differently. For example, add a 'highlighted' class to a menu item to make it stand out, or add 'external-link' class to links pointing to external sites. Configure the 'class' attribute (enabled by default) and enter class names when editing menu items.
Opening links in new windows
Configure certain menu links to open in new browser windows using the target attribute. The module provides '_blank' and '_self' options by default. Useful for external links, PDF documents, or resources that should remain accessible while the main site stays open.
Adding accessibility attributes
Enhance menu accessibility by adding ARIA attributes. Configure attributes like 'aria-label', 'aria-describedby', or 'role' in the YAML configuration to allow content editors to add accessibility improvements to specific menu items.
Styling menu item containers
Apply CSS classes or other attributes to the wrapping <li> element instead of the link itself. Useful for adding dropdown indicators, special styling containers, or JavaScript hooks. Use attributes prefixed with 'container_' or set 'container: true' in the attribute configuration.
Adding data attributes for JavaScript
Add custom data-* attributes to menu links for JavaScript functionality. For example, add 'data-analytics-category' for tracking, 'data-modal-trigger' for modal dialogs, or 'data-submenu-id' for custom dropdown behavior. Define these as textfield attributes in the YAML configuration.
Icon integration with menu items
When using icon libraries, add icon classes to menu items. Configure a 'data-icon' or icon class attribute that content editors can use to specify which icon should appear with each menu item, enabling visual enhancement without code changes.
Tips
- Install the YAML Editor module for a better editing experience when configuring attributes
- Container attributes can be created by either prefixing the attribute name with 'container_' or by adding 'container: true' to the attribute configuration
- Use the 'checkboxes' type for attributes where multiple values can be selected, such as multiple CSS classes from a predefined list
- The 'managed_file' type allows file uploads (like images) to be associated with menu items - specify 'upload_location' to set the upload directory
- When navigating from the configuration page to a menu item edit form, the Attributes section automatically opens with the first field focused
- Class attributes are automatically converted to arrays for proper HTML rendering, so they work correctly with Drupal's attribute system
- For multilingual sites, attributes set on the default translation can be inherited by other translations when 'Only affect the default translation' is enabled
Technical Details
Admin Pages 1
/admin/config/menu_link_attributes/config
Configuration page for defining which HTML attributes are available on menu link edit forms. Attributes are defined using YAML syntax, where each attribute can have a label, description, type, options, and default value.
Permissions 2
Hooks 2
hook_form_menu_link_content_form_alter
Alters the menu link content form to add attribute input fields based on the module configuration. Adds an 'Attributes' details element containing form fields for each configured attribute.
template_preprocess_menu
Preprocesses menu templates to apply container attributes to the <li> elements. Recursively processes all menu items including nested children.
Troubleshooting 5
Ensure you have the 'Use menu link attributes' permission. Also verify that you are editing a menu link content entity (custom menu links), as the module only works with menu_link_content entities, not system-defined menu links.
Make sure your theme uses the standard menu template that respects item attributes. Check that the attribute is properly configured with 'container_' prefix or 'container: true' setting. Clear cache after configuration changes.
Verify your YAML syntax is correct. Common issues include incorrect indentation (use spaces, not tabs), missing colons after keys, or unescaped special characters. Install YAML Editor module for syntax highlighting.
The module automatically converts class values to arrays. If you're programmatically accessing these values, expect an array format. The update hook 8001 fixes malformed class attributes from older versions.
Run database updates (drush updb) to apply update hooks that add labels and descriptions to default attributes.
Security Notes 3
- The 'Administer menu link attributes' permission is marked as restricted access because it allows defining arbitrary HTML attributes that could potentially be misused
- Attribute values entered by users are subject to Drupal's standard sanitization when rendered
- Be cautious when adding attributes that could enable XSS if not properly handled by themes