Hands-On With the Menu Link Attributes Module: Step-by-Step Drupal Configuration

Hands-On With the Menu Link Attributes Module: Step-by-Step Drupal Configuration

Valerie Gaudette
Valerie Gaudette
October 28, 2025
Last updated : February 15, 2026
October 28, 2025

If you've ever tried to add a CSS class to a specific menu link in Drupal, you know the frustration. Core Drupal doesn't give you an easy way to add attributes like classes, IDs, or target="_blank" to individual menu links through the admin interface. You're stuck either writing custom code or overriding templates for something that should be simple.

The Menu Link Attributes module fixes this problem. It lets content editors add HTML attributes directly to menu links through Drupal's interface. No code required. Whether you need to style specific links, improve accessibility with ARIA attributes, or control link behavior, this module makes it straightforward.

In this guide, you'll learn how to install, configure, and use the Menu Link Attributes module in Drupal 11. You'll also see how to add custom attributes programmatically when you need more control.

Prerequisites

Before starting, make sure you have:

  • A Drupal 11 site up and running (the module also works with Drupal 10)
  • Composer installed for dependency management
  • Administrator access to your Drupal site
  • Basic familiarity with Drupal's menu system
  • SSH access or terminal access if you're using Drush commands

The Menu Link Attributes module is actively maintained and has over 80,000 reported installations. As of late 2024, it's fully compatible with Drupal 11 and receives regular security updates.

Step-by-Step Implementation

Step 1: Install the Module

Start by installing the module through Composer. Open your terminal, navigate to your Drupal root directory, and run:

composer require drupal/menu_link_attributes

Once Composer finishes downloading the module and its dependencies, enable it using Drush:

drush en menu_link_attributes -y

Alternatively, you can enable it through the admin interface by going to Extend (/admin/modules), finding "Menu Link Attributes" in the list, checking the box, and clicking "Install."

Step 2: Set User Permissions

After installation, you need to grant permissions to users who should be able to add attributes to menu links. Navigate to People > Permissions (/admin/people/permissions) and look for the "Use menu link attributes" permission.

We've found that most sites benefit from giving this permission to content editor roles, not just administrators. This allows your content team to manage link attributes without needing full admin access.

Grant the permission to appropriate roles like:

  • Content Editor
  • Site Administrator
  • Marketing Manager (if they manage menus)

Save your permission changes before moving on.

Step 3: Configure Available Attributes

The module lets you control which attributes editors can use. Go to Configuration > Menu Link Attributes (/admin/config/menu_link_attributes/config) to set this up.

By default, you'll see common attributes available:

  • class - For CSS styling
  • id - For unique identifiers
  • target - To control where links open
  • rel - For relationship attributes like nofollow
  • aria-label - For accessibility

You can enable or disable any of these based on your needs. If you only want editors to add CSS classes and nothing else, disable the other options.

To add custom attributes, you'll need to create a YAML configuration file. Here's an example that adds data attributes for analytics tracking:

attributes:
  data-track-click:
    label: 'Click Tracking ID'
    description: 'Analytics tracking identifier'
  data-category:
    label: 'Analytics Category'
    options:
      navigation: 'Navigation'
      footer: 'Footer'
      sidebar: 'Sidebar'

Save this configuration and clear your cache to make the new attributes available.

Step 4: Add Attributes to Menu Links

Now for the actual implementation. Navigate to Structure > Menus (/admin/structure/menu) and choose a menu to work with. Let's use the Main Navigation menu as an example.

Either create a new menu link or edit an existing one. You'll notice a new "Attributes" fieldset in the menu link form. This is where the magic happens.

Let's say you want to create an external link that opens in a new tab with proper security attributes:

1. Click "Add link" in your menu
2. Enter the link title: "Documentation"
3. Enter the link URL: "https://example.com/docs"
4. Open the "Attributes" fieldset
5. Add these values:

  • Class: external-link documentation-link
  • Target: _blank
  • Rel: noopener noreferrer

Save the menu link and you're done.

Step 5: Add Attributes Programmatically

Sometimes you need to set menu link attributes through code, especially when creating links during module installation or data migration. Here's how to do it:

use Drupal\menu_link_content\Entity\MenuLinkContent;

// Create a menu link with attributes
$menu_link = MenuLinkContent::create([
  'title' => 'Support Portal',
  'link' => [
    'uri' => 'https://support.example.com',
    'options' => [
      'attributes' => [
        'class' => ['external-link', 'support-link'],
        'target' => '_blank',
        'rel' => 'noopener noreferrer',
        'aria-label' => 'Opens in a new window',
      ],
    ],
  ],
  'menu_name' => 'main',
  'weight' => 10,
  'expanded' => FALSE,
]);
$menu_link->save();

For existing menu links, you can update attributes like this:

// Load an existing menu link
$menu_link = MenuLinkContent::load($menu_link_id);

// Get the current link options
$link_field = $menu_link->get('link')->first();
$options = $link_field->getOptions();

// Add or update attributes
$options['attributes']['class'][] = 'updated-class';
$options['attributes']['data-modified'] = 'true';

// Save the updated options
$link_field->setOptions($options);
$menu_link->save();

Step 6: Create Custom Attribute Types

If you need attributes beyond the defaults, you can add custom ones through a module. Create a custom module (let's call it custom_menu_attributes) and add this configuration:

First, create custom_menu_attributes.menu_link_attributes.yml:

data-menu-icon:
  label: 'Menu Icon'
  description: 'Icon class for menu item'
data-tooltip:
  label: 'Tooltip Text'
  description: 'Hover tooltip for the menu link'

Then implement a hook to make these attributes available in the form:

/**
 * Implements hook_entity_base_field_info_alter().
 */
function custom_menu_attributes_entity_base_field_info_alter(&$fields, \Drupal\Core\Entity\EntityTypeInterface $entity_type) {
  if ($entity_type->id() === 'menu_link_content') {
    if (isset($fields['link'])) {
      $fields['link']->setDisplayOptions('form', [
        'type' => 'link_attributes',
        'settings' => [
          'enabled_attributes' => [
            'class' => TRUE,
            'id' => TRUE,
            'target' => TRUE,
            'rel' => TRUE,
            'data-menu-icon' => TRUE,
            'data-tooltip' => TRUE,
          ],
        ],
      ]);
    }
  }
}

Clear your cache after adding this code, and your custom attributes will appear in the menu link form.

Common Mistakes to Avoid

Mistake 1: Forgetting to Clear Cache

The most common issue we see is attributes not appearing after configuration changes. Drupal caches menu rendering aggressively, so always clear your cache after:

  • Installing the module
  • Changing attribute configuration
  • Adding custom attributes
  • Updating templates

Use drush cr or visit Configuration > Performance and click "Clear all caches."

Mistake 2: Theme Template Issues

Your theme needs to output the attributes for them to appear. Check that your menu templates include the attributes variable. In your menu.html.twig or menu--main.html.twig, make sure you have:

<a{{ item.attributes }}>{{ item.title }}</a>

Not:

<a href="{{ item.url }}">{{ item.title }}</a>

Our experience shows that many custom themes miss this, especially ones migrated from Drupal 7 or earlier versions.

Mistake 3: Security Issues with Target="_blank"

When adding target="_blank" to open links in new tabs, always include rel="noopener noreferrer". Without these, the opened page can access your site's window object, creating security vulnerabilities.

Mistake 4: Overusing ID Attributes

IDs must be unique on a page. If you add an ID to a menu link that appears in multiple menus (like footer and header), you'll create invalid HTML. Use classes instead for styling multiple elements.

Mistake 5: Not Considering Mobile Menus

Attributes you add affect all versions of a menu. If your mobile menu JavaScript relies on specific classes, adding conflicting attributes might break functionality. Test thoroughly on all devices.

Testing and Verification Steps

After setting up menu link attributes, verify everything works correctly:

1. Browser Inspector Check

Right-click on your menu links and inspect the HTML. Confirm your attributes appear in the rendered markup:

<a href="/about" 
   class="external-link custom-style" 
   target="_blank" 
   rel="noopener noreferrer"
   aria-label="Learn more about our company">
   About Us
</a>

2. Accessibility Testing

Use browser accessibility tools to verify ARIA attributes work correctly:

  • Chrome DevTools Lighthouse
  • WAVE browser extension
  • Screen reader testing (NVDA or JAWS on Windows, VoiceOver on Mac)

3. JavaScript Functionality

If you're using classes or IDs for JavaScript targeting, test that your scripts still work:

// Test that your JavaScript selectors find the elements
document.querySelectorAll('.external-link').forEach(link => {
  console.log('Found external link:', link.href);
});

4. Cross-browser Testing

Verify your styled menu links appear correctly in:

  • Chrome/Edge
  • Firefox
  • Safari
  • Mobile browsers

5. Performance Check

Menu attributes shouldn't impact performance, but if you've added many custom attributes, check your page load times. Use Chrome DevTools Performance tab to ensure menu rendering isn't slowing down your site.

Conclusion

The Menu Link Attributes module solves a real problem in Drupal: giving content editors control over individual menu link properties without touching code. You've learned how to install it, configure available attributes, and add both standard and custom attributes to your menu links. You've also seen how to avoid common pitfalls and properly test your implementation.

Working with teams has taught us that this module dramatically reduces the back-and-forth between content editors and developers. Instead of filing tickets for simple class additions or link behavior changes, editors can handle these tasks themselves, freeing developers to focus on more complex work.

If you're building a Drupal site that needs flexible menu styling, accessibility improvements, or specific link behaviors, the Menu Link Attributes module is essential. It's particularly valuable for marketing sites where different teams need to manage various menu sections with different styling and tracking requirements.

Setting up menu attributes correctly from the start saves hours of custom development time later. If you're planning a Drupal project and need help determining which modules and configuration will best support your content team's workflow, we can review your requirements and recommend an architecture that gives editors the control they need while maintaining clean, maintainable code.

Share this article