1. Skip to note content

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

   Contributed by Drew Jaynes — 3 years ago

   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:

   <ul id="%1$s" class="%2$s">%3$s</ul>
   

   items_wrap after:

   %3$s
   

   Example:

   wp_nav_menu( array( 'items_wrap' => '%3$s' ) );
   

2. Skip to note content

   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

   Contributed by Drew Jaynes — 3 years ago

   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 );
   	}
   }
   

   Expand full source codeCollapse full source code

3. Skip to note content

   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

   Contributed by Drew Jaynes — 3 years ago

   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'
   ) );
   

4. Skip to note content

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

   Contributed by Codex — 3 years ago

   Default example

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

   <?php wp_nav_menu(); ?>
   

5. Skip to note content

   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

   Contributed by Drew Jaynes — 3 years ago

   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()
   ) );
   

6. Skip to note content

   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

   Contributed by Drew Jaynes — 3 years ago

   Targeting a specific menu

   wp_nav_menu( array(
   	'menu' => 'Project Nav'
   ) );
   

7. Skip to note content

   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

   Contributed by Drew Jaynes — 3 years ago

   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 );
   

   Expand full source codeCollapse full source code

8. Skip to note content

   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

   Contributed by willgorham — 1 year ago

   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}

9. Skip to note content

   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

   Contributed by Codex — 3 years ago

   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' );
   

   Expand full source codeCollapse full source code

10. Skip to note content

    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

    Contributed by Colin Devroe — 10 months ago

    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
    }
    

11. Skip to note content

    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

    Contributed by netzgestaltung — 3 months ago

    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);
    

    Expand full source codeCollapse full source code

12. Skip to note content

    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

    Contributed by kdevanti — 9 months ago

    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"]

13. Skip to note content

    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

    Contributed by Drew Jaynes — 3 years ago

    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>'
    ) );
    

14. Skip to note content

    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

    Contributed by wp_smith — 1 year ago

    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?

Have a note or feedback to contribute?