walker_nav_menu_start_el │ filter-hook │ WP 3.0.0

Allows you to change the output of a menu item's opening element.

By default, the opening element is built as follows in WordPress core:

$item_output = $args->before;
$item_output .= '<a'. $attributes .'>';
$item_output .= $args->link_before . $title . $args->link_after;
$item_output .= '</a>';
$item_output .= $args->after;

Thus, the filter receives the generated HTML for the menu item link, including the values of the before, link_before, link_after, and after arguments.

There is currently no filter for changing a menu item's <li> and </li> tags. To do that, create a custom equivalent of the Walker_Nav_Menu class.

Usage

add_filter( 'walker_nav_menu_start_el', 'wp_kama_walker_nav_menu_start_el_filter', 10, 4 );

/**
 * Function for `walker_nav_menu_start_el` filter-hook.
 * 
 * @param string   $item_output The menu item's starting HTML output.
 * @param WP_Post  $menu_item   Menu item data object.
 * @param int      $depth       Depth of menu item. Used for padding.
 * @param stdClass $args        An object of wp_nav_menu() arguments.
 *
 * @return string
 */
function wp_kama_walker_nav_menu_start_el_filter( $item_output, $menu_item, $depth, $args ){
	// filter...
	return $item_output;
}

$item_output(string)

HTML of the menu item's opening element (<a>...</a>).

$item(WP_Post)

Current menu item object. Example:

WP_Post Object
(
	[ID] => 265
	[post_author] => 1
	[post_date] => 2018-04-07 09:45:46
	[post_date_gmt] => 2018-04-07 06:45:46
	[post_content] =>
	[post_title] => Contact Us
	[post_excerpt] =>
	[post_status] => publish
	[comment_status] => closed
	[ping_status] => closed
	[post_password] =>
	[post_name] => 265
	[to_ping] =>
	[pinged] =>
	[post_modified] => 2018-04-19 00:20:29
	[post_modified_gmt] => 2018-04-18 21:20:29
	[post_content_filtered] =>
	[post_parent] => 0
	[guid] => http://wp-test.com/?p=265
	[menu_order] => 1
	[post_type] => nav_menu_item
	[post_mime_type] =>
	[comment_count] => 0
	[filter] => raw
	[db_id] => 265
	[menu_item_parent] => 0
	[object_id] => 214
	[object] => page
	[type] => post_type
	[type_label] => Page
	[url] => http://wp-test.com/post-99
	[title] => Contact Us
	[target] =>
	[attr_title] =>
	[description] =>
	[classes] => Array
		(
			[0] =>
			[1] => menu-item
			[2] => menu-item-type-post_type
			[3] => menu-item-object-page
		)

	[xfn] =>
	[current] =>
	[current_item_ancestor] =>
	[current_item_parent] =>
)

$depth(int)

Menu item level used for indentation. Top-level menu items have $depth = 0, their children have $depth = 1, and so on. Added in version 4.1.0.

$args(stdClass)

Object containing parameters from wp_nav_menu(). Example:

stdClass Object
(
	[menu] => WP_Term Object
		(
			[term_id] => 21
			[name] => My First Menu
			[slug] => my-first-menu
			[term_group] => 0
			[term_taxonomy_id] => 21
			[taxonomy] => nav_menu
			[description] =>
			[parent] => 0
			[count] => 3
			[filter] => raw
		)

	[container] => div
	[container_class] =>
	[container_id] =>
	[menu_class] => primary-menu
	[menu_id] =>
	[echo] => 1
	[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] => primary
)

Examples

#1 Wrap links in a div container

add_filter( 'walker_nav_menu_start_el', 'filter_walker_nav_menu_start_el', 10, 4 );

function filter_walker_nav_menu_start_el( $item_output, $item, $depth, $args ) {
	return '<div class="wrap-link">' . $item_output . '</div>';
}

Suppose the menu has this structure:

• Vegetables
• My article
  • Another article

And this HTML:

<div class="menu-second-menu-container">
	<ul id="menu-second-menu" class="menu">
		<li id="menu-item-317" class="menu-item menu-item-type-taxonomy menu-item-object-category menu-item-317">
			<a href="http://wp-test.com/category/vegetables">Vegetables</a>
		</li>
		<li id="menu-item-322" class="menu-item menu-item-type-post_type menu-item-object-post menu-item-has-children menu-item-322">
			<a href="http://wp-test.com/my-article">My article</a>
			<ul class="sub-menu">
				<li id="menu-item-321" class="menu-item menu-item-type-post_type menu-item-object-post menu-item-321">
					<a href="http://wp-test.com/another-article">Another article</a>
				</li>
			</ul>
		</li>
	</ul>
</div>

After applying the example filter, the HTML becomes:

<div class="menu-second-menu-container">
	<ul id="menu-second-menu" class="menu">
		<li id="menu-item-317" class="menu-item menu-item-type-taxonomy menu-item-object-category menu-item-317">
			<div class="wrap-link">
				<a href="http://wp-test.com/category/vegetables">Vegetables</a>
			</div>
		</li>
		<li id="menu-item-322" class="menu-item menu-item-type-post_type menu-item-object-post menu-item-has-children menu-item-322">
			<div class="wrap-link">
				<a href="http://wp-test.com/my-article">My article</a>
			</div>
			<ul class="sub-menu">
				<li id="menu-item-321" class="menu-item menu-item-type-post_type menu-item-object-post menu-item-321">
					<div class="wrap-link">
						<a href="http://wp-test.com/another-article">Another article</a>
					</div>
				</li>
			</ul>
		</li>
	</ul>
</div>