wp_nav_menu( array $args = array() ): void|string|false

User Contributed Notes

1. Skip to note 26 content

   Marco Panichi 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 45You must log in to vote on the helpfulness of this note

   Here is the ready to use snippet (not a real contribution, more than anything else a shortcut):

   wp_nav_menu( array $args = array(
   	'menu'				=> "", // (int|string|WP_Term) Desired menu. Accepts a menu ID, slug, name, or object.
   	'menu_class'		=> "", // (string) CSS class to use for the ul element which forms the menu. Default 'menu'.
   	'menu_id'			=> "", // (string) The ID that is applied to the ul element which forms the menu. Default is the menu slug, incremented.
   	'container'			=> "", // (string) Whether to wrap the ul, and what to wrap it with. Default 'div'.
   	'container_class'	=> "", // (string) Class that is applied to the container. Default 'menu-{menu slug}-container'.
   	'container_id'		=> "", // (string) The ID that is applied to the container.
   	'fallback_cb'		=> "", // (callable|bool) If the menu doesn't exists, a callback function will fire. Default is 'wp_page_menu'. Set to false for no fallback.
   	'before'			=> "", // (string) Text before the link markup.
   	'after'				=> "", // (string) Text after the link markup.
   	'link_before'		=> "", // (string) Text before the link text.
   	'link_after'		=> "", // (string) Text after the link text.
   	'echo'				=> "", // (bool) Whether to echo the menu or return it. Default true.
   	'depth'				=> "", // (int) How many levels of the hierarchy are to be included. 0 means all. Default 0.
   	'walker'			=> "", // (object) Instance of a custom walker class.
   	'theme_location'	=> "", // (string) Theme location to be used. Must be registered with register_nav_menu() in order to be selectable by the user.
   	'items_wrap'		=> "", // (string) How the list items should be wrapped. Default is a ul with an id and class. Uses printf() format with numbered placeholders.
   	'item_spacing'		=> "", // (string) Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'. Default 'preserve'.
   ) );

   • You should remove the “array $args = ” it always makes my site crash. I love your shortcut, I use it often.

     mgrenierlebleu 2 years ago
2. Skip to note 27 content

   Drew Jaynes 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 44You must log in to vote on the helpfulness of this note

   Different menus for logged-in users

   This example would cause a menu to show for logged-in users and a different menu for users not logged-in.

   wp_nav_menu( array(
   	'theme_location' => is_user_logged_in() ? 'logged-in-menu' : 'logged-out-menu'
   ) );
3. Skip to note 28 content

   Drew Jaynes 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 26You must log in to vote on the helpfulness of this note

   Removing the ul wrap

   This example will remove the unordered list wrap around the list items. Replacing the wrap HTML with the %3$s specifier results in only outputting the HTML list content for the menu items, because items_wrap is built using sprintf()

   items_wrap default before:
   [html]
   <ul id="%1$s" class="%2$s">%3$s</ul>
   [/html]

   items_wrap after:
   [html]
   %3$s
   [/html]

   Example:

   wp_nav_menu( array( 'items_wrap' => '%3$s' ) );
4. Skip to note 29 content

   Drew Jaynes 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 24You must log in to vote on the helpfulness of this note

   Using a Custom Walker Function

   For deeper conditional classes, you’ll need to use a custom walker function (created in the 'walker' => new Your_Walker_Function argument).

   The simplest way to build a new walker function is to copy and extend the default class (Walker_Nav_Menu) from /wp-includes/nav-menu-template.php and simply customize what you need.

   Example:

   This custom walker function will add several conditional classes to your nav menu (i.e. sub-menu, even/odd, etc):

   wp_nav_menu( array(
   	'menu'   => 'Something custom walker',
   	'walker' => new WPDocs_Walker_Nav_Menu()
   ) );
   
   /**
    * Custom walker class.
    */
   class WPDocs_Walker_Nav_Menu extends Walker_Nav_Menu {
   
   	/**
   	 * Starts the list before the elements are added.
   	 *
   	 * Adds classes to the unordered list sub-menus.
   	 *
   	 * @param string $output Passed by reference. Used to append additional content.
   	 * @param int    $depth  Depth of menu item. Used for padding.
   	 * @param array  $args   An array of arguments. @see wp_nav_menu()
   	 */
   	function start_lvl( &$output, $depth = 0, $args = array() ) {
   		// Depth-dependent classes.
   		$indent = ( $depth > 0  ? str_repeat( "\t", $depth ) : '' ); // code indent
   		$display_depth = ( $depth + 1); // because it counts the first submenu as 0
   		$classes = array(
   			'sub-menu',
   			( $display_depth % 2  ? 'menu-odd' : 'menu-even' ),
   			( $display_depth >=2 ? 'sub-sub-menu' : '' ),
   			'menu-depth-' . $display_depth
   		);
   		$class_names = implode( ' ', $classes );
   
   		// Build HTML for output.
   		$output .= "\n" . $indent . '<ul class="' . $class_names . '">' . "\n";
   	}
   
   	/**
   	 * Start the element output.
   	 *
   	 * Adds main/sub-classes to the list items and links.
   	 *
   	 * @param string $output Passed by reference. Used to append additional content.
   	 * @param object $item   Menu item data object.
   	 * @param int    $depth  Depth of menu item. Used for padding.
   	 * @param array  $args   An array of arguments. @see wp_nav_menu()
   	 * @param int    $id     Current item ID.
   	 */
   	function start_el( &$output, $item, $depth = 0, $args = array(), $id = 0 ) {
   		global $wp_query;
   		$indent = ( $depth > 0 ? str_repeat( "\t", $depth ) : '' ); // code indent
   
   		// Depth-dependent classes.
   		$depth_classes = array(
   			( $depth == 0 ? 'main-menu-item' : 'sub-menu-item' ),
   			( $depth >=2 ? 'sub-sub-menu-item' : '' ),
   			( $depth % 2 ? 'menu-item-odd' : 'menu-item-even' ),
   			'menu-item-depth-' . $depth
   		);
   		$depth_class_names = esc_attr( implode( ' ', $depth_classes ) );
   
   		// Passed classes.
   		$classes = empty( $item->classes ) ? array() : (array) $item->classes;
   		$class_names = esc_attr( implode( ' ', apply_filters( 'nav_menu_css_class', array_filter( $classes ), $item ) ) );
   
   		// Build HTML.
   		$output .= $indent . '<li id="nav-menu-item-'. $item->ID . '" class="' . $depth_class_names . ' ' . $class_names . '">';
   
   		// Link attributes.
   		$attributes  = ! empty( $item->attr_title ) ? ' title="'  . esc_attr( $item->attr_title ) .'"' : '';
   		$attributes .= ! empty( $item->target )     ? ' target="' . esc_attr( $item->target     ) .'"' : '';
   		$attributes .= ! empty( $item->xfn )        ? ' rel="'    . esc_attr( $item->xfn        ) .'"' : '';
   		$attributes .= ! empty( $item->url )        ? ' href="'   . esc_attr( $item->url        ) .'"' : '';
   		$attributes .= ' class="menu-link ' . ( $depth > 0 ? 'sub-menu-link' : 'main-menu-link' ) . '"';
   
   		// Build HTML output and pass through the proper filter.
   		$item_output = sprintf( '%1$s<a%2$s>%3$s%4$s%5$s</a>%6$s',
   			$args->before,
   			$attributes,
   			$args->link_before,
   			apply_filters( 'the_title', $item->title, $item->ID ),
   			$args->link_after,
   			$args->after
   		);
   		$output .= apply_filters( 'walker_nav_menu_start_el', $item_output, $item, $depth, $args );
   	}
   }
5. Skip to note 30 content

   willgorham 8 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 11You must log in to vote on the helpfulness of this note

   To clarify link_before vs before, and link_after vs after

   The link_before / link_after values are output WITHIN the link.
   Whereas, before / after values are output OUTSIDE of the link, but within the list item.

   For example:
   {before}{link_before}Link Text{link_after}{after}
6. Skip to note 31 content

   Codex 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note

   Default example

   Shows the first non-empty menu or wp_page_menu().

   [html]
   <?php wp_nav_menu() ; ?>
   [/html]
7. Skip to note 32 content

   Drew Jaynes 10 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 7You must log in to vote on the helpfulness of this note

   Targeting a specific menu with no fallback to wp_page_menu()

   In the case that no menu matching menu is found, it seems that passing a bogus theme_location is the only way to prevent falling back to the first non-empty menu:

   wp_nav_menu( array(
   	'menu'           => 'Project Nav', // Do not fall back to first non-empty menu.
   	'theme_location' => '__no_such_location',
   	'fallback_cb'    => false // Do not fall back to wp_page_menu()
   ) );
8. Skip to note 33 content

   leec87 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   By default, menus are encased with a div container. The options on this page show this parameter as a string to change the element used to contain the menu.

   However, it is not noted here that if you pass false as a value, the container is completely removed leaving just the ul menu element.

   wp_nav_menu(array(
       'container' => false // Removes the container, leaving just the ul element
   ));
9. Skip to note 34 content

   Colin Devroe 8 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

   How to show a placeholder menu if no menu is set up

   Credit: Salcode.

   If you’ve just installed WordPress and activated a theme, there may not be a primary menu yet set up in Appearance > Menus. For these times you may want to show your own, placeholder, menu until that menu is set up.

   To do this, use the fallback callback function. Like so:

   wp_nav_menu( array( 'fallback_cb' => 'custom_primary_menu_fallback', 'menu' => 'menu', 'container' => false, 'menu_id' => 'menu', 'menu_class'=>'', 'theme_location'=>'primary-menu' ) );
   
   function custom_primary_menu_fallback() {
     ?>
     <ul id="menu"><li><a href="/">Home</a></li><li><a href="/wp-admin/nav-menus.php">Set primary menu</a></li></ul>
     <?php
   }
10. Skip to note 35 content

    kdevanti 8 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

    Simple shortcode for displaying a menu
    this will allow you to display a menu in where ever you add the shortcode, lots of room to expand the $args but left it simple.

    function get_menu($args){
        $menu = isset($atts['menu']) ? $atts['menu'] : '';
        ob_start();
        wp_nav_menu(array(
            'menu' => $menu
        ) );
        return ob_get_clean();
    }
    add_shortcode('get_menu', 'get_menu');

    Usage Example:

    [get_menu menu="Main Menu"]
11. Skip to note 36 content

    Drew Jaynes 10 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    Targeting a specific menu

    wp_nav_menu( array(
    	'menu' => 'Project Nav'
    ) );
12. Skip to note 37 content

    Ruturaaj Patki 7 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    How to add .active class to active menu item

    Here is the code:

    add_filter('nav_menu_css_class' , 'special_nav_class' , 10 , 2);
    function special_nav_class($classes, $item){
         if( in_array('current-menu-item', $classes) ){
                 $classes[] = 'active ';
         }
         return $classes;
    }
13. Skip to note 38 content

    Lovro Hrust 4 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    It is not mentioned that container parameter by default accepts only ‘div’, ‘nav’ and falsy value (”, false, null). If you want to extend accepted tag arguments and wrap menu parent ul tag in something else, you have to use wp_nav_menu_container_allowedtags filter and add desired tag to the array. However, for the most uses, default two tags are most logical.
14. Skip to note 39 content

    Codex 10 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    How to add a parent class for menu item

    Sometimes you may need to add a class to a menu item if it has sub-menus.

    /**
     * Add a parent CSS class for nav menu items.
     *
     * @param array  $items The menu items, sorted by each menu item's menu order.
     * @return array (maybe) modified parent CSS class.
     */
    function wpdocs_add_menu_parent_class( $items ) {
    	$parents = array();
    
    	// Collect menu items with parents.
    	foreach ( $items as $item ) {
    		if ( $item->menu_item_parent && $item->menu_item_parent > 0 ) {
    			$parents[] = $item->menu_item_parent;
    		}
    	}
    
    	// Add class.
    	foreach ( $items as $item ) {
    		if ( in_array( $item->ID, $parents ) ) {
    			$item->classes[] = 'menu-parent-item';
    		}
    	}
    	return $items;
    }
    add_filter( 'wp_nav_menu_objects', 'wpdocs_add_menu_parent_class' );
15. Skip to note 40 content

    netzgestaltung 7 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    instead of large walkers you can simply filter menu item class names

    // adds useful menu-item class names
    function your_theme_menu_item_class( $classes, $item ) {
    
      // Add slugs to menu-items
      if ( 'category' == $item->object ) {
        $category = get_category( $item->object_id );
        $classes[] = 'category-' . $category->slug;
      } elseif ( 'format' == $item->object ){
        $format = get_term($item->object_id);
        $classes[] = 'format-' . $format->slug;
      }
      return $classes;  
    }
    
    add_filter( 'nav_menu_css_class', 'your_theme_menu_item_class', 10, 2);
16. Skip to note 41 content

    Drew Jaynes 10 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Adding Conditional Classes to Menu Items

    This example would let you add a custom class to a menu item based on the condition you specify. Don’t forget to change the condition.

    /**
     * Filter the CSS class for a nav menu based on a condition.
     *
     * @param array  $classes The CSS classes that are applied to the menu item's <li> element.
     * @param object $item    The current menu item.
     * @return array (maybe) modified nav menu class.
     */
    function wpdocs_special_nav_class( $classes, $item ) {
    	if ( is_single() && 'Blog' == $item->title ) {
    		// Notice you can change the conditional from is_single() and $item->title
    		$classes[] = "special-class";
    	}
    	return $classes;
    }
    add_filter( 'nav_menu_css_class' , 'wpdocs_special_nav_class' , 10, 2 );
17. Skip to note 42 content

    Jean-Philippe 5 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Removing the default div container

    In order to remove the default div container in which the menu is encased, just :

    1. Use the parameter ‘container’ in the array
    2. And leave it empty.

    Like in the following example :

    wp_nav_menu(array(
        'container' => '', // Leaving it empty removes the <div> container.
    ));
18. Skip to note 43 content

    MarcGuay 4 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    The only accepted values for the container argument, by default, are div and nav so any other value will cause it to not display.

    • FYI, null (no quotation marks) is also a valid option for the ‘container’ argument, if you don’t want to add a container around the menu.

      Joe Westcott 3 years ago
19. Skip to note 44 content

    Marks1973 3 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    I’ve found really useful the echo arg.

    // 1) store the menu in a var:
    $my_wp_nav_menu = wp_nav_menu(
    	array(
    		'echo' => false
    	)
    );
    
    // 2) do whatever you want with the menu array before displaying it:
    //    (just an) example: remove slashes from menu voices:
    $my_wp_nav_menu = str_replace( array( '%5C', '\' ) ), '', $my_wp_nav_menu );
    
    echo $my_wp_nav_menu;
20. Skip to note 45 content

    Lovro Hrust 3 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Menu slug

    Menu slugs are constructed as: [menu name]-menu

    I.e., for menu named ‘main’, slug will be ‘main-menu‘

    You can find menu slugs in terms database table.
21. Skip to note 46 content

    jave.web 1 year ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    If you are looking for a way how to replace the menu item title (what’s displayed) with e.g. custom HTML or wrap the text in some HTML, you are looking for the `nav_menu_item_title` filter
22. Skip to note 47 content

    yaalsez 5 months ago

    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    The difference between the 'menu' and 'theme_location' parameters in the wp_nav_menu() function is not clearly explained in this article. However, I believe there is a distinction, as they appear to serve different purposes.

    The 'menu' parameter relies on the name of the menu that is assigned when it is created in the WordPress admin panel. Therefore, it is recommended to match the parameter value to the name given when creating the menu. However, if this is not done, the ‘theme_location’ parameter will be used instead, which will display the menu that is attached or selected for that location. This location must be previously registered with the register_nav_menu() function in the functions.php file.

    Therefore, for developers, it is wise to set the 'theme_location' parameter instead of the 'menu' parameter. Keep in mind that the way the menu is displayed is defined in the order described in the Usage section of this article.
23. Skip to note 48 content

    samjco 3 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note

    Make a shortcode to show menu in editor

    // Function that will return our WordPress menu
    function show_wp_menu_function($atts, $content = null) {
    	
    	extract(shortcode_atts(array(  
    		'menu'            => '', 
    		'container'       => 'div', 
    		'container_class' => '', 
    		'container_id'    => '', 
    		'menu_class'      => 'menu', 
    		'menu_id'         => '',
    		'echo'            => true,
    		'fallback_cb'     => 'wp_page_menu',
    		'before'          => '',
    		'after'           => '',
    		'link_before'     => '',
    		'link_after'      => '',
    		'depth'           => 0,
    		'walker'          => '',
    		'theme_location'  => ''), 
    		$atts));
     
     
    	return wp_nav_menu( array( 
    		'menu'            => $menu, 
    		'container'       => $container, 
    		'container_class' => $container_class, 
    		'container_id'    => $container_id, 
    		'menu_class'      => $menu_class, 
    		'menu_id'         => $menu_id,
    		'echo'            => false,
    		'fallback_cb'     => $fallback_cb,
    		'before'          => $before,
    		'after'           => $after,
    		'link_before'     => $link_before,
    		'link_after'      => $link_after,
    		'depth'           => $depth,
    		'walker'          => $walker,
    		'theme_location'  => $theme_location));
    }
    //Create the shortcode
    add_shortcode("show_wp_menu", "show_wp_menu_function");

    To use simply:
    [show_wp_menu menu="wp_menu_name_here" menu_class="my_menu_class"]
24. Skip to note 49 content

    Drew Jaynes 10 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: -3You must log in to vote on the helpfulness of this note

    Adding a Word at the Beginning of the Menu

    This example will allows you to add the word of your choice to the beginning of your menu as a list item. In this example, the word “Menu:” is added at the beginning. You may want to set an id on the list item (“item-id” in this example) so that you can use CSS to style it.

    wp_nav_menu( array(
    	'theme_location' => 'primary',
    	'items_wrap'     => '<ul><li id="item-id"><?php __( 'Menu:', 'textdomain' ); ?></li>%3$s</ul>'
    ) );
25. Skip to note 50 content

    wp_smith 8 years ago

    You must log in to vote on the helpfulness of this noteVote results for this note: -15You must log in to vote on the helpfulness of this note

    I’m a little confused about the parameters “before / after” and “link_before / link_after”.

    This reference says “before / after” are inside the link, including the link-text, and “link_before / link_after” are outside the link, including the link.

    What confuses me:
    Some tutorials say, it’s exactly the other way round, (inside / outside):
    here and here
    I’m coming to the same result, when looking at one of my active WP-installations.

    What is correct?

    • You were right to be confused: the arguments were in fact switched in terms of documentation. This has been fixed in [37561] for 4.6. Thanks for the tip!

      Drew Jaynes 8 years ago