Creating Custom Menu Walkers To Add Descriptions In Wordpress

The Problem: Menus Lack Descriptive Text

One limitation of standard WordPress menus is that they only display the menu item title by default. There is no built-in way to add descriptive text or details about a link without custom coding. This makes the menus less informative and engaging for site visitors.

For example, a menu item titled “Services” doesn’t explain what lies behind that link or why visitors should click. Adding a description like “Learn more about our consulting and design services for enterprises” provides useful context.

Understanding Menu Walkers in WordPress

In WordPress, specialized classes called “walkers” handle the PHP logic for displaying different types of site navigation menus. They control the HTML markup output for the menus on the front-end of your site.

Table of Contents

By default, WordPress uses a core walker class called Walker_Nav_Menu to handle most standard menus. This builds out the structure of the menu using ul/li tags and outputs the title attribute for links.

However, the functionality of this default class is limited. To customize or extend menus beyond what it offers, developers can create custom walker classes.

Building your own PHP menu walker gives you total control over the HTML and presentation of menus without having to filter or hook into existing structures. This allows adding additional markup like descriptions, images, or complex layouts.

Extending the Nav Walker Class

Rather than writing a menu walker class from complete scratch, it’s often easier to extend the existing Walker_Nav_Menu class built into WordPress and override specific methods.

This way you tap into the heavy lifting it already does, while injecting your own customizations. The Nav_Walker class handles most of the structural logic like building nested lists and walking the menu tree.

To customize output, look for methods like start_el() and end_el(). These template methods are called for each menu item and let you override how menu links get printed.

By extending Walker_Nav_Menu and adding your own start_el() code, you can keep the core traversal logic and wrap custom markup around individual links.

Outputting Descriptions in start_el()

A key method for adding rich data to menus is start_el(). This prints the HTML for the start of each menu item, including the opening link tag.

Here you can check the $item parameter passed to the method, which contains an object with all kinds of data about the current menu item like title, URL, and any description content saved.

If a description exists, you can access it with $item->description and print it inside a paragraph after the link HTML using standard PHP echo or print statements.

  public function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
    // Output anchor tag
    parent::start_el( ... );
    
    // Check for description data
    if ( !empty( $item->description ) ) {   
      // Print description in paragraph
      echo '' . $item->description . ''; 
    }
  }

Applying Custom Walker to Menus

Once your custom menu walker is built, you need to connect it to your theme’s menu locations to apply the custom output.

This happens in functions.php or an init hook, when registering menus with wp_nav_menu(). Instead of leaving the args empty, specify your walker by setting ‘walker’ => new Custom_Nav_Walker()

The key points are instantiating your class, and passing the walker object to wp_nav_menu() to override the default. After this change, visit menu settings to refresh cached data.

$walker = new Custom_Nav_Walker();
 
wp_nav_menu( array(
  'theme_location' => 'primary', 
  'walker' => $walker,
) );

Additional Tips and Tricks

To take your custom menus even further, here are some additional tips for features you can build on top of your new walker class:

Styling the description content

Since descriptions print outside the link, style them differently from menu items using CSS. Reduce text size, use border-bottom padding, or add color labels indicating types.

Supporting multiple description fields

Let content editors add multiple blurbs per item, like a short teaser and a longer body, by checking custom field names in your walker class.

Fallback for browsers without JavaScript

Ensure accessibility by still including descriptions for no-JS visitors even if they don’t see the dropdown.

Summary

In summary, building custom menu walkers in WordPress provides tremendous flexibility lacking in out-of-the-box navigation components.

By extending the default walker classes, you tap into robust existing code handling much of the heavy logic for traversing and displaying menus. This makes it simpler than writing walkers completely from scratch.

Small tweaks to the markup by overriding just the output methods you need gives freedom to craft richer, more descriptive menus, layers expandable accordions, off-canvas slide-outs, or other innovative navigation.

Creating Custom Menu Walkers To Add Descriptions In WordPress