How do I generate a custom menu/sub-menu system using wp_get_nav_menu_items in WordPress?

How do I generate a custom menu/sub-menu system using wp_get_nav_menu_items in WordPress?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Building Custom Nav Menus with wp_get_nav_menu_items and Nested Hierarchies

When you need to customize the output of a WordPress navigation menu, relying solely on wp_nav_menu() often hits a wall. That function generates clean HTML5 semantics, but it lacks granular control over attributes like specific classes or custom content injection between links. If your requirement involves injecting a description (excerpt) alongside the title and maintaining a nested sub-menu structure, you must move to manual rendering using wp_get_nav_menu_items().

The core challenge lies in detecting hierarchy. The WP_Nav_Menu_Item object returned by wp_get_nav_menu_items() contains a property called $item->menu_item_parent. This integer holds the ID of the parent item if one exists; otherwise, it is zero or null. By iterating through the top-level items first and then recursively fetching their children, you can reconstruct the nested <ul> structure required for dropdowns.

Here is how to approach generating the specific HTML structure you described. You will need to separate your logic into two distinct loops: one for the main menu level and one for rendering sub-menus.

First, retrieve the menu object and its items. Note that we must explicitly set the order parameter to ensure consistent output, and we often need to filter out empty items.

$menu_name = 'main-nav';
$locations = get_nav_menu_locations();
$menu_id = $locations[$menu_name]; // Get the ID of the assigned menu location

if ( ! $menu_id ) {
    return; // Handle case where menu is not assigned to a location
}

$menu_items = wp_get_nav_menu_items( $menu_id, [ 'order' => 'ASC' ] );

// Filter out empty items if necessary
$menu_items = array_filter( $menu_items, function( $item ) {
    return ! is_null( $item ) && $item->ID !== '';
} );

foreach ( $menu_items as $top_level_item ) :
    
    // Determine the link and content for the main item
    // We assume the custom logic involving get_page() for excerpts here
    $link = get_permalink( $top_level_item->object_id ); 
    // If using custom post types or external links, adjust accordingly
    
    echo '<li class="item">';
    
    echo '<a href="' . esc_url( $link ) . '" class="title">' . esc_html( get_the_title( $top_level_item->object_id ) ) . '</a>';
    echo '<a href="' . esc_url( $link ) . '" class="desc">' . esc_html( get_post_field( 'post_excerpt', $top_level_item->object_id ) ) . '</a>';

    // Check if this item has children (sub-menu)
    $children = wp_get_nav_menu_items( $top_level_item->ID, [ 'order' => 'ASC' ] );
    $children = array_filter( $children, function( $child ) { return ! is_null( $child ) && $child->ID !== ''; } );

    if ( ! empty( $children ) ) :
        echo '<ul class="sub-menu">';
        
        foreach ( $children as $child_item ) :
            // Apply the same logic for child items
            $child_link = get_permalink( $child_item->object_id );
            
            echo '<li class="item">';
            echo '<a href="' . esc_url( $child_link ) . '" class="title">' . esc_html( get_the_title( $child_item->object_id ) ) . '</a>';
            echo '<a href="' . esc_url( $child_link ) . '" class="desc">' . esc_html( get_post_field( 'post_excerpt', $child_item->object_id ) ) . '</a>';
            echo '</li>';
            
        endforeach;

        echo '</ul>';
    endif;

    echo '</li>';

endforeach;

Handling the Data Source

In your original code snippet, you were retrieving data using get_post_meta( $item->ID, '_menu_item_object_id', true ). This is valid if you are dealing with a specific custom meta setup, but for standard WordPress menus, $item->object_id is the direct property holding the ID of the linked object (e.g., a Post, Page, or Custom Post Type). Using $item->object_id is more efficient and reliable than querying post meta for the ID itself.

Furthermore, the logic get_page( $id ) works well for standard pages, but if your menu items link to posts, categories, tags, or external URLs, that approach will fail. The code above uses $top_level_item->object_id directly with get_permalink() and get_the_title(), which is the robust way to handle mixed content types in navigation menus.

Performance Considerations

A potential pitfall in this recursive approach is the number of database queries. If you have a top-level item with many children, and each child has grandchildren, you are making multiple calls to wp_get_nav_menu_items(). While this keeps the logic clean and readable, it can degrade performance on large sites. For most standard themes, however, the overhead is negligible compared to the complexity saved by not hardcoding HTML strings manually.

If you find yourself needing to traverse deep hierarchies frequently, consider caching the menu items using wp_cache_get() and wp_cache_set(), or utilizing a dedicated navigation library that abstracts this recursion for better performance.

Our network