wp_nav_menu

Displays a navigation menu.

Description

(object|false|void) wp_nav_menu( (array) $args = array() ); 

Returns (object|false|void)

Menu output if $echo is false, false if there are no items or no menu was found.

Parameters (1)

0. $args — Optional. (array) => array()
Array of nav menu arguments.

Options

  • menu (int|string|WP_Term) => ''

    Desired menu. Accepts (matching in order) id, slug, name, menu object.

  • menu_class (string) => 'menu'

    CSS class to use for the ul element which forms the menu.

  • menu_id (string) => is the menu slug, incremented

    The ID that is applied to the ul element which forms the menu.

array(

    /**
     * Desired menu. Accepts (matching in order) id, slug, name, menu object.
     *
     * @type int|string|WP_Term
     * @default ''
     */
    'menu' => '',

    /**
     * CSS class to use for the ul element which forms the menu.
     *
     * @type string
     * @default 'menu'
     */
    'menu_class' => 'menu',

    /**
     * The ID that is applied to the ul element which forms the menu.
     *
     * @type string
     * @default is the menu slug, incremented
     */
    'menu_id' => is the menu slug, incremented
);        


Usage

  1. if ( !function_exists( 'wp_nav_menu' ) ) { 
  2. require_once ABSPATH . WPINC . '/nav-menu-template.php'; 
  3.  
  4. // Optional. Array of nav menu arguments. 
  5. $args = array( 
  6. 'menu' => '', 
  7. 'menu_class' => 'menu', 
  8. 'menu_id' => is the menu slug, incremented 
  9. ); 
  10.  
  11. // NOTICE! Understand what this does before running. 
  12. $result = wp_nav_menu($args); 
  13.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/nav-menu-template.php  
  1. function wp_nav_menu( $args = array() ) { 
  2. static $menu_id_slugs = array(); 
  3.  
  4. $defaults = array( 'menu' => '', 'container' => 'div', 'container_class' => '', 'container_id' => '', 'menu_class' => 'menu', 'menu_id' => '',  
  5. 'echo' => true, 'fallback_cb' => 'wp_page_menu', 'before' => '', 'after' => '', 'link_before' => '', 'link_after' => '', 'items_wrap' => '<ul id="%1$s" class="%2$s">%3$s</ul>', 'item_spacing' => 'preserve',  
  6. 'depth' => 0, walker => '', 'theme_location' => '' ); 
  7.  
  8. $args = wp_parse_args( $args, $defaults ); 
  9.  
  10. if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) { 
  11. // invalid value, fall back to default. 
  12. $args['item_spacing'] = $defaults['item_spacing']; 
  13.  
  14. /** 
  15. * Filters the arguments used to display a navigation menu. 
  16. * @since 3.0.0 
  17. * @see wp_nav_menu() 
  18. * @param array $args Array of wp_nav_menu() arguments. 
  19. */ 
  20. $args = apply_filters( 'wp_nav_menu_args', $args ); 
  21. $args = (object) $args; 
  22.  
  23. /** 
  24. * Filters whether to short-circuit the wp_nav_menu() output. 
  25. * Returning a non-null value to the filter will short-circuit 
  26. * wp_nav_menu(), echoing that value if $args->echo is true,  
  27. * returning that value otherwise. 
  28. * @since 3.9.0 
  29. * @see wp_nav_menu() 
  30. * @param string|null $output Nav menu output to short-circuit with. Default null. 
  31. * @param stdClass $args An object containing wp_nav_menu() arguments. 
  32. */ 
  33. $nav_menu = apply_filters( 'pre_wp_nav_menu', null, $args ); 
  34.  
  35. if ( null !== $nav_menu ) { 
  36. if ( $args->echo ) { 
  37. echo $nav_menu; 
  38. return; 
  39.  
  40. return $nav_menu; 
  41.  
  42. // Get the nav menu based on the requested menu 
  43. $menu = wp_get_nav_menu_object( $args->menu ); 
  44.  
  45. // Get the nav menu based on the theme_location 
  46. if ( ! $menu && $args->theme_location && ( $locations = get_nav_menu_locations() ) && isset( $locations[ $args->theme_location ] ) ) 
  47. $menu = wp_get_nav_menu_object( $locations[ $args->theme_location ] ); 
  48.  
  49. // get the first menu that has items if we still can't find a menu 
  50. if ( ! $menu && !$args->theme_location ) { 
  51. $menus = wp_get_nav_menus(); 
  52. foreach ( $menus as $menu_maybe ) { 
  53. if ( $menu_items = wp_get_nav_menu_items( $menu_maybe->term_id, array( 'update_post_term_cache' => false ) ) ) { 
  54. $menu = $menu_maybe; 
  55. break; 
  56.  
  57. if ( empty( $args->menu ) ) { 
  58. $args->menu = $menu; 
  59.  
  60. // If the menu exists, get its items. 
  61. if ( $menu && ! is_wp_error($menu) && !isset($menu_items) ) 
  62. $menu_items = wp_get_nav_menu_items( $menu->term_id, array( 'update_post_term_cache' => false ) ); 
  63.  
  64. /** 
  65. * If no menu was found: 
  66. * - Fall back (if one was specified), or bail. 
  67. * If no menu items were found: 
  68. * - Fall back, but only if no theme location was specified. 
  69. * - Otherwise, bail. 
  70. */ 
  71. if ( ( !$menu || is_wp_error($menu) || ( isset($menu_items) && empty($menu_items) && !$args->theme_location ) ) 
  72. && isset( $args->fallback_cb ) && $args->fallback_cb && is_callable( $args->fallback_cb ) ) 
  73. return call_user_func( $args->fallback_cb, (array) $args ); 
  74.  
  75. if ( ! $menu || is_wp_error( $menu ) ) 
  76. return false; 
  77.  
  78. $nav_menu = $items = ''; 
  79.  
  80. $show_container = false; 
  81. if ( $args->container ) { 
  82. /** 
  83. * Filters the list of HTML tags that are valid for use as menu containers. 
  84. * @since 3.0.0 
  85. * @param array $tags The acceptable HTML tags for use as menu containers. 
  86. * Default is array containing 'div' and 'nav'. 
  87. */ 
  88. $allowed_tags = apply_filters( 'wp_nav_menu_container_allowedtags', array( 'div', 'nav' ) ); 
  89. if ( is_string( $args->container ) && in_array( $args->container, $allowed_tags ) ) { 
  90. $show_container = true; 
  91. $class = $args->container_class ? ' class="' . esc_attr( $args->container_class ) . '"' : ' class="menu-'. $menu->slug .'-container"'; 
  92. $id = $args->container_id ? ' id="' . esc_attr( $args->container_id ) . '"' : ''; 
  93. $nav_menu .= '<'. $args->container . $id . $class . '>'; 
  94.  
  95. // Set up the $menu_item variables 
  96.  
  97. $sorted_menu_items = $menu_items_with_children = array(); 
  98. foreach ( (array) $menu_items as $menu_item ) { 
  99. $sorted_menu_items[ $menu_item->menu_order ] = $menu_item; 
  100. if ( $menu_item->menu_item_parent ) 
  101. $menu_items_with_children[ $menu_item->menu_item_parent ] = true; 
  102.  
  103. // Add the menu-item-has-children class where applicable 
  104. if ( $menu_items_with_children ) { 
  105. foreach ( $sorted_menu_items as &$menu_item ) { 
  106. if ( isset( $menu_items_with_children[ $menu_item->ID ] ) ) 
  107. $menu_item->classes[] = 'menu-item-has-children'; 
  108.  
  109. unset( $menu_items, $menu_item ); 
  110.  
  111. /** 
  112. * Filters the sorted list of menu item objects before generating the menu's HTML. 
  113. * @since 3.1.0 
  114. * @param array $sorted_menu_items The menu items, sorted by each menu item's menu order. 
  115. * @param stdClass $args An object containing wp_nav_menu() arguments. 
  116. */ 
  117. $sorted_menu_items = apply_filters( 'wp_nav_menu_objects', $sorted_menu_items, $args ); 
  118.  
  119. $items .= walk_nav_menu_tree( $sorted_menu_items, $args->depth, $args ); 
  120. unset($sorted_menu_items); 
  121.  
  122. // Attributes 
  123. if ( ! empty( $args->menu_id ) ) { 
  124. $wrap_id = $args->menu_id; 
  125. } else { 
  126. $wrap_id = 'menu-' . $menu->slug; 
  127. while ( in_array( $wrap_id, $menu_id_slugs ) ) { 
  128. if ( preg_match( '#-(\d+)$#', $wrap_id, $matches ) ) 
  129. $wrap_id = preg_replace('#-(\d+)$#', '-' . ++$matches[1], $wrap_id ); 
  130. else 
  131. $wrap_id = $wrap_id . '-1'; 
  132. $menu_id_slugs[] = $wrap_id; 
  133.  
  134. $wrap_class = $args->menu_class ? $args->menu_class : ''; 
  135.  
  136. /** 
  137. * Filters the HTML list content for navigation menus. 
  138. * @since 3.0.0 
  139. * @see wp_nav_menu() 
  140. * @param string $items The HTML list content for the menu items. 
  141. * @param stdClass $args An object containing wp_nav_menu() arguments. 
  142. */ 
  143. $items = apply_filters( 'wp_nav_menu_items', $items, $args ); 
  144. /** 
  145. * Filters the HTML list content for a specific navigation menu. 
  146. * @since 3.0.0 
  147. * @see wp_nav_menu() 
  148. * @param string $items The HTML list content for the menu items. 
  149. * @param stdClass $args An object containing wp_nav_menu() arguments. 
  150. */ 
  151. $items = apply_filters( "wp_nav_menu_{$menu->slug}_items", $items, $args ); 
  152.  
  153. // Don't print any markup if there are no items at this point. 
  154. if ( empty( $items ) ) 
  155. return false; 
  156.  
  157. $nav_menu .= sprintf( $args->items_wrap, esc_attr( $wrap_id ), esc_attr( $wrap_class ), $items ); 
  158. unset( $items ); 
  159.  
  160. if ( $show_container ) 
  161. $nav_menu .= '</' . $args->container . '>'; 
  162.  
  163. /** 
  164. * Filters the HTML content for navigation menus. 
  165. * @since 3.0.0 
  166. * @see wp_nav_menu() 
  167. * @param string $nav_menu The HTML content for the navigation menu. 
  168. * @param stdClass $args An object containing wp_nav_menu() arguments. 
  169. */ 
  170. $nav_menu = apply_filters( 'wp_nav_menu', $nav_menu, $args ); 
  171.  
  172. if ( $args->echo ) 
  173. echo $nav_menu; 
  174. else 
  175. return $nav_menu;