Displays a navigation menu.

Parameters

$argsarrayoptional

Array of nav menu arguments.

• 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.
• container_aria_label string
  The aria-label attribute that is applied to the container when it’s a nav element.
• fallback_cb callable|false
  If the menu doesn’t exist, 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.
  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. Uses printf() format with numbered placeholders. Default is a ul with an id and class.
• item_spacing string
  Whether to preserve whitespace within the menu’s HTML.
  Accepts 'preserve' or 'discard'. Default 'preserve'.

Default:array()

Return

More Information

Usage

wp_nav_menu( $args );

Given a theme_location parameter, the function displays the menu assigned to that location. If no such location exists or no menu is assigned to it, the parameter fallback_cb will determine what is displayed.

If not given a theme_location parameter, the function displays

• the menu matching the ID, slug, or name given by the menu parameter;
• otherwise, the first non-empty menu;
• otherwise (or if the menu given by menu is empty), output of the function given by the fallback_cb parameter (wp_page_menu(), by default);
• otherwise nothing.

Menu Item CSS Classes

The following classes are applied to menu items, i.e. to the HTML <li> tags, generated by wp_nav_menu():

All Menu Items

• .menu-item
  This class is added to every menu item.
• .menu-item-has-children
  This class is added to menu item which has sub-items .
• .menu-item-object-{object}
  This class is added to every menu item, where {object} is either a post type or a taxonomy.
• .menu-item-object-category
  This class is added to menu items that correspond to a category.
• .menu-item-object-tag
  This class is added to menu items that correspond to a tag.
• .menu-item-object-page
  This class is added to menu items that correspond to static pages.
• .menu-item-object-{custom}
  This class is added to menu items that correspond to a custom post type or a custom taxonomy.
• .menu-item-type-{type}
  This class is added to every menu item, where {type} is either “post_type” or “taxonomy”.
• .menu-item-type-post_type
  This class is added to menu items that correspond to post types: i.e. static pages or custom post types.
• .menu-item-type-taxonomy
  This class is added to menu items that correspond to taxonomies: i.e. categories, tags, or custom taxonomies.

Current-Page Menu Items

• .current-menu-item
  This class is added to menu items that correspond to the currently rendered page.

Current-Page Parent Menu Items

• .current-menu-parent
  This class is added to menu items that correspond to the hierarchical parent of the currently rendered page.
• .current-{object}-parent
  This class is added to menu items that correspond to the hierachical parent of the currently rendered object, where {object} corresponds to the the value used for .menu-item-object-{object}.
• .current-{type}-parent
  This class is added to menu items that correspond to the hierachical parent of the currently rendered type, where {type} corresponds to the the value used for .menu-item-type-{type}.

Current-Page Ancestor Menu Items

• .current-menu-ancestor
  This class is added to menu items that correspond to a hierarchical ancestor of the currently rendered page.
• .current-{object}-ancestor
  This class is added to menu items that correspond to a hierachical ancestor of the currently rendered object, where {object} corresponds to the the value used for .menu-item-object-{object}.
• .current-{type}-ancestor
  This class is added to menu items that correspond to a hierachical ancestor of the currently rendered type, where {type} corresponds to the the value used for .menu-item-type-{type}.

Site Front Page Menu Items

• .menu-item-home
  This class is added to menu items that correspond to the site front page.

Backward Compatibility with wp_page_menu()

The following classes are added to maintain backward compatibility with the [[Function Reference/wp_page_menu|wp_page_menu() ]] function output:

• .page_item
  This class is added to menu items that correspond to a static page.
• .page_item_has_children
  This class is added to menu items that have sub pages to it.
• .page-item-$ID
  This class is added to menu items that correspond to a static page, where $ID is the static page ID.
• .current_page_item
  This class is added to menu items that correspond to the currently rendered static page.
• .current_page_parent
  This class is added to menu items that correspond to the hierarchical parent of the currently rendered static page.
• .current_page_ancestor
  This class is added to menu items that correspond to a hierarchical ancestor of the currently rendered static page.

Source

function wp_nav_menu( $args = array() ) {
	static $menu_id_slugs = array();

	$defaults = array(
		'menu'                 => '',
		'container'            => 'div',
		'container_class'      => '',
		'container_id'         => '',
		'container_aria_label' => '',
		'menu_class'           => 'menu',
		'menu_id'              => '',
		'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',
		'depth'                => 0,
		'walker'               => '',
		'theme_location'       => '',
	);

	$args = wp_parse_args( $args, $defaults );

	if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {
		// Invalid value, fall back to default.
		$args['item_spacing'] = $defaults['item_spacing'];
	}

	/**
	 * Filters the arguments used to display a navigation menu.
	 *
	 * @since 3.0.0
	 *
	 * @see wp_nav_menu()
	 *
	 * @param array $args Array of wp_nav_menu() arguments.
	 */
	$args = apply_filters( 'wp_nav_menu_args', $args );
	$args = (object) $args;

	/**
	 * Filters whether to short-circuit the wp_nav_menu() output.
	 *
	 * Returning a non-null value from the filter will short-circuit wp_nav_menu(),
	 * echoing that value if $args->echo is true, returning that value otherwise.
	 *
	 * @since 3.9.0
	 *
	 * @see wp_nav_menu()
	 *
	 * @param string|null $output Nav menu output to short-circuit with. Default null.
	 * @param stdClass    $args   An object containing wp_nav_menu() arguments.
	 */
	$nav_menu = apply_filters( 'pre_wp_nav_menu', null, $args );

	if ( null !== $nav_menu ) {
		if ( $args->echo ) {
			echo $nav_menu;
			return;
		}

		return $nav_menu;
	}

	// Get the nav menu based on the requested menu.
	$menu = wp_get_nav_menu_object( $args->menu );

	// Get the nav menu based on the theme_location.
	$locations = get_nav_menu_locations();
	if ( ! $menu && $args->theme_location && $locations && isset( $locations[ $args->theme_location ] ) ) {
		$menu = wp_get_nav_menu_object( $locations[ $args->theme_location ] );
	}

	// Get the first menu that has items if we still can't find a menu.
	if ( ! $menu && ! $args->theme_location ) {
		$menus = wp_get_nav_menus();
		foreach ( $menus as $menu_maybe ) {
			$menu_items = wp_get_nav_menu_items( $menu_maybe->term_id, array( 'update_post_term_cache' => false ) );
			if ( $menu_items ) {
				$menu = $menu_maybe;
				break;
			}
		}
	}

	if ( empty( $args->menu ) ) {
		$args->menu = $menu;
	}

	// If the menu exists, get its items.
	if ( $menu && ! is_wp_error( $menu ) && ! isset( $menu_items ) ) {
		$menu_items = wp_get_nav_menu_items( $menu->term_id, array( 'update_post_term_cache' => false ) );
	}

	/*
	 * If no menu was found:
	 *  - Fall back (if one was specified), or bail.
	 *
	 * If no menu items were found:
	 *  - Fall back, but only if no theme location was specified.
	 *  - Otherwise, bail.
	 */
	if ( ( ! $menu || is_wp_error( $menu ) || ( isset( $menu_items ) && empty( $menu_items ) && ! $args->theme_location ) )
		&& isset( $args->fallback_cb ) && $args->fallback_cb && is_callable( $args->fallback_cb ) ) {
			return call_user_func( $args->fallback_cb, (array) $args );
	}

	if ( ! $menu || is_wp_error( $menu ) ) {
		return false;
	}

	$nav_menu = '';
	$items    = '';

	$show_container = false;
	if ( $args->container ) {
		/**
		 * Filters the list of HTML tags that are valid for use as menu containers.
		 *
		 * @since 3.0.0
		 *
		 * @param string[] $tags The acceptable HTML tags for use as menu containers.
		 *                       Default is array containing 'div' and 'nav'.
		 */
		$allowed_tags = apply_filters( 'wp_nav_menu_container_allowedtags', array( 'div', 'nav' ) );

		if ( is_string( $args->container ) && in_array( $args->container, $allowed_tags, true ) ) {
			$show_container = true;
			$class          = $args->container_class ? ' class="' . esc_attr( $args->container_class ) . '"' : ' class="menu-' . $menu->slug . '-container"';
			$id             = $args->container_id ? ' id="' . esc_attr( $args->container_id ) . '"' : '';
			$aria_label     = ( 'nav' === $args->container && $args->container_aria_label ) ? ' aria-label="' . esc_attr( $args->container_aria_label ) . '"' : '';
			$nav_menu      .= '<' . $args->container . $id . $class . $aria_label . '>';
		}
	}

	// Set up the $menu_item variables.
	_wp_menu_item_classes_by_context( $menu_items );

	$sorted_menu_items        = array();
	$menu_items_with_children = array();
	foreach ( (array) $menu_items as $menu_item ) {
		/*
		 * Fix invalid `menu_item_parent`. See: https://core.trac.wordpress.org/ticket/56926.
		 * Compare as strings. Plugins may change the ID to a string.
		 */
		if ( (string) $menu_item->ID === (string) $menu_item->menu_item_parent ) {
			$menu_item->menu_item_parent = 0;
		}

		$sorted_menu_items[ $menu_item->menu_order ] = $menu_item;
		if ( $menu_item->menu_item_parent ) {
			$menu_items_with_children[ $menu_item->menu_item_parent ] = true;
		}
	}

	// Add the menu-item-has-children class where applicable.
	if ( $menu_items_with_children ) {
		foreach ( $sorted_menu_items as &$menu_item ) {
			if ( isset( $menu_items_with_children[ $menu_item->ID ] ) ) {
				$menu_item->classes[] = 'menu-item-has-children';
			}
		}
	}

	unset( $menu_items, $menu_item );

	/**
	 * Filters the sorted list of menu item objects before generating the menu's HTML.
	 *
	 * @since 3.1.0
	 *
	 * @param array    $sorted_menu_items The menu items, sorted by each menu item's menu order.
	 * @param stdClass $args              An object containing wp_nav_menu() arguments.
	 */
	$sorted_menu_items = apply_filters( 'wp_nav_menu_objects', $sorted_menu_items, $args );

	$items .= walk_nav_menu_tree( $sorted_menu_items, $args->depth, $args );
	unset( $sorted_menu_items );

	// Attributes.
	if ( ! empty( $args->menu_id ) ) {
		$wrap_id = $args->menu_id;
	} else {
		$wrap_id = 'menu-' . $menu->slug;

		while ( in_array( $wrap_id, $menu_id_slugs, true ) ) {
			if ( preg_match( '#-(\d+)$#', $wrap_id, $matches ) ) {
				$wrap_id = preg_replace( '#-(\d+)$#', '-' . ++$matches[1], $wrap_id );
			} else {
				$wrap_id = $wrap_id . '-1';
			}
		}
	}
	$menu_id_slugs[] = $wrap_id;

	$wrap_class = $args->menu_class ? $args->menu_class : '';

	/**
	 * Filters the HTML list content for navigation menus.
	 *
	 * @since 3.0.0
	 *
	 * @see wp_nav_menu()
	 *
	 * @param string   $items The HTML list content for the menu items.
	 * @param stdClass $args  An object containing wp_nav_menu() arguments.
	 */
	$items = apply_filters( 'wp_nav_menu_items', $items, $args );
	/**
	 * Filters the HTML list content for a specific navigation menu.
	 *
	 * @since 3.0.0
	 *
	 * @see wp_nav_menu()
	 *
	 * @param string   $items The HTML list content for the menu items.
	 * @param stdClass $args  An object containing wp_nav_menu() arguments.
	 */
	$items = apply_filters( "wp_nav_menu_{$menu->slug}_items", $items, $args );

	// Don't print any markup if there are no items at this point.
	if ( empty( $items ) ) {
		return false;
	}

	$nav_menu .= sprintf( $args->items_wrap, esc_attr( $wrap_id ), esc_attr( $wrap_class ), $items );
	unset( $items );

	if ( $show_container ) {
		$nav_menu .= '</' . $args->container . '>';
	}

	/**
	 * Filters the HTML content for navigation menus.
	 *
	 * @since 3.0.0
	 *
	 * @see wp_nav_menu()
	 *
	 * @param string   $nav_menu The HTML content for the navigation menu.
	 * @param stdClass $args     An object containing wp_nav_menu() arguments.
	 */
	$nav_menu = apply_filters( 'wp_nav_menu', $nav_menu, $args );

	if ( $args->echo ) {
		echo $nav_menu;
	} else {
		return $nav_menu;
	}
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘pre_wp_nav_menu’, string|null $output, stdClass $args )

Filters whether to short-circuit the wp_nav_menu() output.

apply_filters( ‘wp_nav_menu’, string $nav_menu, stdClass $args )

Filters the HTML content for navigation menus.

apply_filters( ‘wp_nav_menu_args’, array $args )

Filters the arguments used to display a navigation menu.

apply_filters( ‘wp_nav_menu_container_allowedtags’, string[] $tags )

Filters the list of HTML tags that are valid for use as menu containers.

apply_filters( ‘wp_nav_menu_items’, string $items, stdClass $args )

Filters the HTML list content for navigation menus.

apply_filters( ‘wp_nav_menu_objects’, array $sorted_menu_items, stdClass $args )

Filters the sorted list of menu item objects before generating the menu’s HTML.

apply_filters( “wp_nav_menu_{$menu->slug}_items”, string $items, stdClass $args )

Filters the HTML list content for a specific navigation menu.

Changelog