Custom Menus Implementation: Use theme_location instead of menu in wp_nav_menu() 

In several recent Theme reviews, I have noticed that Themes are implementing custom navigation menus incorrectly, primarily due to the arguments passed to wp_nav_menu. For example:

<?php
wp_nav_menu( array(
    'menu' => 'primary-nav'
) );
?>

Notice what’s wrong there? Yeah: the 'menu' parameter.

By passing the 'menu' parameter, the Theme is telling WordPress, “display the user-defined menu with  this slug“. This parameter will only work in one of two cases:

  1. As a matter of serendipity, the user has created a custom menu with the slug “primary-nav” (i.e. a custom menu named “Primary Nav”)
  2. As a matter of chance, the user has only defined one custom menu, which WordPress will use as an alternate, when it cannot find a menu with the slug “primary-nav”

In pretty much all other cases, the user-defined menu assigned to a given Theme location will not output correctly.

Instead, Themes should only and always pass the 'theme_location' parameter to wp_nav_menu(). The 'theme_location' parameter corresponds to the array keys passed to register_nav_menus(), like so:

register_nav_menus( array(
    'primary-nav' => "Primary Menu",
    'footer-nav' => "Footer Menu"
) );

The array key is the 'theme_location', and the array value is the title that displays under the “Theme Locations” meta box on the Dashboard -> Appearance -> Menus screen. So, Themes should pass those array keys to calls to wp_nav_menu(), like so:

<?php
wp_nav_menu( array(
    'theme_location' => 'primary-nav'
) );
?>

That way, custom navigation menus will work properly:

  1. Theme registers custom menu Theme locations, via register_nav_menus()
  2. User creates custom menus, via the Dashboard -> Appearance -> Menus screen
  3. User assigns custom menus to Theme locations, via the “Theme Locations” meta box on the Dashboard -> Appearance -> Menus screen
  4. Theme outputs custom menus in appropriate locations within the Theme template, via wp_nav_menu()

Hopefully this post will help eliminate a few Theme development headaches.