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

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$argsarrayoptional

Array of nav menu arguments.Default: array()

• $menuint|string|WP_Termdefault: empty

  Desired menu. Accepts a menu ID, slug, name, or object.

• $menu_classstringdefault: 'menu'

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

• $menu_idstringdefault: is the menu slug, incremented

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

• $containerstringdefault: 'div'

  Whether to wrap the ul, and what to wrap it with.

• $container_classstringdefault: 'menu-{menu slug}-container'

  Class that is applied to the container.

• $container_idstringdefault: empty

  The ID that is applied to the container.

• $container_aria_labelstringdefault: empty

  The aria-label attribute that is applied to the container when it's a nav element.

• $fallback_cbcallable|falsedefault: is 'wp_page_menu'. Set to false for no fallback

  If the menu doesn't exist, a callback function will fire.

• $beforestringdefault: empty

  Text before the link markup.

• $afterstringdefault: empty

  Text after the link markup.

• $link_beforestringdefault: empty

  Text before the link text.

• $link_afterstringdefault: empty

  Text after the link text.

• $echobooldefault: true

  Whether to echo the menu or return it.

• $depthintdefault: 0. Default 0

  How many levels of the hierarchy are to be included. 0 means all.

• $walkerobjectdefault: empty

  Instance of a custom walker class.

• $theme_locationstring

  Theme location to be used. Must be registered with register_nav_menu() in order to be selectable by the user.

• $items_wrapstringdefault: is a ul with an id and class

  How the list items should be wrapped. Uses printf() format with numbered placeholders.

• $item_spacingstringdefault: 'preserve'

  Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.

Return value

void|string|false

Void if 'echo' argument is true, menu output if 'echo' is false.
False if there are no items or no menu was found.

Performance profile

How much work a call to wp_nav_menu() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_term().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

43–202

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 328.

Plugin surface

7 hooks

Third-party callbacks on 'wp_nav_menu_args', 'pre_wp_nav_menu', 'wp_nav_menu_container_allowedtags' run inside this call, and their cost is not bounded by anything here.

Called by

2

2 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_term()one call below wp_nav_menu()
• optionoption read or writeget_option()one call below wp_nav_menu()

Further down the call graph this can also reach cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 17 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_nav_menu() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 7

7 hooks fire while wp_nav_menu() runs, in this order:

1. 1
   apply_filters( wp_nav_menu_args )filterline 97 (+40 into the body)

   Filters the arguments used to display a navigation menu.

2. 2
   apply_filters( pre_wp_nav_menu )filterline 113 (+56 into the body)

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

3. 3
   apply_filters( wp_nav_menu_container_allowedtags )filterline 184 (+127 into the body)

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

4. 4
   apply_filters( wp_nav_menu_objects )filterline 234 (+177 into the body)

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

5. 5
   apply_filters( wp_nav_menu_items )filterline 267 (+210 into the body)

   Filters the HTML list content for navigation menus.

6. 6
   apply_filters( wp_nav_menu_{$menu->slug}_items )filterline 278 (+221 into the body)

   Filters the HTML list content for a specific navigation menu.

7. 7
   apply_filters( wp_nav_menu )filterline 302 (+245 into the body)

   Filters the HTML content for navigation menus.

Uses · 10

• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_get_nav_menu_object()Returns a navigation menu object.
• get_nav_menu_locations()Retrieves all registered navigation menu locations and the menus assigned to them.
• wp_get_nav_menus()Returns all navigation menu objects.
• wp_get_nav_menu_items()Retrieves all menu items of a navigation menu.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• esc_attr()Escaping for HTML attributes.
• _wp_menu_item_classes_by_context()Adds the class property classes for the current context, if applicable.
• walk_nav_menu_tree()Retrieves the HTML list content for nav menu items.

Used by · 2

• WP_Customize_Nav_Menus::render_nav_menu_partial()Renders a specific menu via wp_nav_menu() using the supplied arguments.
• WP_Nav_Menu_Widget::widget()Outputs the content for the current Navigation Menu widget instance.

Source code

View on Trac ↗View on GitHub ↗

57function wp_nav_menu( $args = array() ) {58	static $menu_id_slugs = array();59 60	$defaults = array(61		'menu'                 => '',62		'container'            => 'div',63		'container_class'      => '',64		'container_id'         => '',65		'container_aria_label' => '',66		'menu_class'           => 'menu',67		'menu_id'              => '',68		'echo'                 => true,69		'fallback_cb'          => 'wp_page_menu',70		'before'               => '',71		'after'                => '',72		'link_before'          => '',73		'link_after'           => '',74		'items_wrap'           => '<ul id="%1$s" class="%2$s">%3$s</ul>',75		'item_spacing'         => 'preserve',76		'depth'                => 0,77		'walker'               => '',78		'theme_location'       => '',79	);80 81	$args = wp_parse_args( $args, $defaults );82 83	if ( ! in_array( $args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {84		// Invalid value, fall back to default.85		$args['item_spacing'] = $defaults['item_spacing'];86	}87 88	/**89	 * Filters the arguments used to display a navigation menu.90	 *91	 * @since 3.0.092	 *93	 * @see wp_nav_menu()94	 *95	 * @param array $args Array of wp_nav_menu() arguments.96	 */97	$args = apply_filters( 'wp_nav_menu_args', $args );98	$args = (object) $args;99 100	/**101	 * Filters whether to short-circuit the wp_nav_menu() output.102	 *103	 * Returning a non-null value from the filter will short-circuit wp_nav_menu(),104	 * echoing that value if $args->echo is true, returning that value otherwise.105	 *106	 * @since 3.9.0107	 *108	 * @see wp_nav_menu()109	 *110	 * @param string|null $output Nav menu output to short-circuit with. Default null.111	 * @param stdClass    $args   An object containing wp_nav_menu() arguments.112	 */113	$nav_menu = apply_filters( 'pre_wp_nav_menu', null, $args );114 115	if ( null !== $nav_menu ) {116		if ( $args->echo ) {117			echo $nav_menu;118			return;119		}120 121		return $nav_menu;122	}123 124	// Get the nav menu based on the requested menu.125	$menu = wp_get_nav_menu_object( $args->menu );126 127	// Get the nav menu based on the theme_location.128	$locations = get_nav_menu_locations();129	if ( ! $menu && $args->theme_location && $locations && isset( $locations[ $args->theme_location ] ) ) {130		$menu = wp_get_nav_menu_object( $locations[ $args->theme_location ] );131	}132 133	// Get the first menu that has items if we still can't find a menu.134	if ( ! $menu && ! $args->theme_location ) {135		$menus = wp_get_nav_menus();136		foreach ( $menus as $menu_maybe ) {

Changelog

Introduced in 3.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.7.7 tag, from src/wp-includes/nav-menu-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.