WordPress Walker Nav Menu Example: Customize Menu Markup Safely

Last reviewed: April 23, 2026

Navigation menus look simple until a theme needs accessible dropdown markup, custom attributes, analytics labels, or a design system class structure that the default output does not provide. A custom walker can solve that problem, but it can also create broken menus if it skips escaping or accessibility attributes.

This guide shows how to customize WordPress menu markup with Walker_Nav_Menu while preserving safe output, predictable classes, and fallbacks.

Start with a registered menu location

<?php
add_action( 'after_setup_theme', 'vulnwp_register_menu_locations' );

function vulnwp_register_menu_locations() {
	register_nav_menus(
		array(
			'primary' => __( 'Primary Menu', 'vulnwp' ),
		)
	);
}

A menu location gives editors a stable place to assign navigation. It is better than hard-coding a menu ID that may differ between environments.

Create a small custom walker

class VulnWP_Primary_Menu_Walker extends Walker_Nav_Menu {
	public function start_lvl( &$output, $depth = 0, $args = null ) {
		$indent = str_repeat( "\t", $depth );
		$output .= "\n" . $indent . '<ul class="menu__submenu" data-depth="' . esc_attr( (string) ( $depth + 1 ) ) . '">' . "\n";
	}

	public function start_el( &$output, $item, $depth = 0, $args = null, $id = 0 ) {
		$classes   = empty( $item->classes ) ? array() : (array) $item->classes;
		$classes[] = 'menu__item';

		if ( in_array( 'menu-item-has-children', $classes, true ) ) {
			$classes[] = 'menu__item--has-children';
		}

		$class_names = implode( ' ', array_map( 'sanitize_html_class', array_filter( $classes ) ) );
		$output     .= '<li class="' . esc_attr( $class_names ) . '">';

		$atts = array(
			'class' => 'menu__link',
			'href'  => ! empty( $item->url ) ? $item->url : '',
		);

		if ( ! empty( $item->target ) ) {
			$atts['target'] = $item->target;
		}

		if ( ! empty( $item->xfn ) ) {
			$atts['rel'] = $item->xfn;
		}

		$attributes = '';
		foreach ( $atts as $attr => $value ) {
			if ( '' === $value ) {
				continue;
			}

			$attributes .= ' ' . $attr . '="' . esc_attr( $value ) . '"';
		}

		$title = apply_filters( 'the_title', $item->title, $item->ID );
		$output .= '<a' . $attributes . '>' . esc_html( $title ) . '</a>';
	}
}

This walker only changes the markup needed for a custom class system. It does not rewrite every method, which reduces maintenance risk when WordPress core behavior changes.

Render the menu

wp_nav_menu(
	array(
		'theme_location' => 'primary',
		'container'      => 'nav',
		'container_class' => 'site-navigation',
		'menu_class'     => 'menu',
		'fallback_cb'    => false,
		'walker'         => new VulnWP_Primary_Menu_Walker(),
	)
);

fallback_cb is set to false so an unassigned production menu does not unexpectedly print a list of pages. On client sites, you may prefer a controlled fallback that links to a setup page for administrators only.

Accessibility pass

A walker should not only satisfy visual requirements. Test keyboard navigation, visible focus states, submenu open behavior, touch behavior, and screen reader announcements. If dropdowns require JavaScript, keep the walker responsible for semantic markup and let JavaScript add runtime state such as aria-expanded.

Production checklist

• Register menu locations with register_nav_menus().
• Keep the walker as small as possible.
• Escape URLs, titles, attributes, and class names.
• Keep editor-managed menu labels safe with esc_html().
• Decide explicitly whether a fallback menu should appear.
• Test nested menus with real editor-created items.

Common mistakes

• Copying a large walker from an old theme. Old snippets often miss modern accessibility and escaping expectations.
• Trusting menu titles. Editors can change labels, so output must be escaped.
• Hard-coding menu IDs. IDs vary between local, staging, and production.
• Using CSS classes as logic without checking depth. Nested menus need deliberate behavior.
• Breaking fallbacks. Decide what happens when no menu is assigned.

Related reading

Navigation assets should be loaded through the wp_enqueue_script example. If your menu links to custom content, pair this with the custom post type guide.

References and further reading

• WordPress Code Reference: wp_nav_menu()
• WordPress Code Reference: Walker_Nav_Menu
• WordPress Code Reference: register_nav_menus()