Retrieving WordPress Menu Items: The Right Way and Why Database Queries Are Usually a Bad Idea
When you need to iterate through the items of your primary menu in a WordPress theme or plugin, the most common stumbling block is encountering empty output when using wp_get_nav_menu_items(). This isn't usually a bug in the function itself; it's almost always a configuration issue regarding how the menu is registered and assigned.
The function returns an array of WP_Nav_Menu_Item objects. If you are getting blank results, the first thing to check is whether the menu actually has items attached to it. In WordPress, a "menu" is distinct from a "theme location." You can register a location like 'primary' in your theme's functions.php, but unless you explicitly assign a named menu object to that location, wp_get_nav_menu_items('primary') will return nothing.
To fix this, you must ensure that an actual menu exists in the database and is assigned to the primary location. This is typically done via the Appearance > Menus screen or programmatically during theme setup. Once assigned, the function populates with data. Here is a standard implementation pattern:
// Retrieve items for the 'primary' location
$menu_items = wp_get_nav_menu_items( 'primary', array( 'walker' => new Walker_Nav_Menu() ) );
if ( ! empty( $menu_items ) ) {
foreach ( $menu_items as $item ) {
// Access properties like title, URL, and classes
echo '<li><a href="' . esc_url( $item->url ) . '">' . esc_html( $item->title ) . '</a></li>';
}
}
The third argument in wp_get_nav_menu_items() is critical. It accepts an array of arguments, including walker. If you omit the walker or pass an invalid one, the function might behave unexpectedly depending on the WordPress version, though often it defaults to a standard walker. However, the most frequent cause of failure remains the lack of assignment between the menu object and the theme location.
Why You Should Avoid Direct Database Queries
You asked if there is a way to get menu items directly from the database without using WordPress methods. Technically, yes. The wp_posts table stores menu items (where post_type = 'nav_menu_item'), and the wp_term_relationships table links them to locations. You could write a complex SQL query joining wp_posts, wp_term_taxonomy, and wp_terms.
However, this approach is strongly discouraged for several reasons:
- Caching: WordPress caches menu data extensively. Bypassing the API means you bypass these caches, leading to unnecessary database load on every request.
- Maintenance: The schema of WordPress tables can change slightly between major versions (e.g., moving from
wp_prefix customizations). Hardcoding table names makes your code fragile. - Hooks and Filters: The
wp_get_nav_menu_items()function runs through hooks likeget_nav_menu_items. These allow you to modify items before rendering, handle permissions, or apply filters you might not know about until you've written raw SQL.
Direct database access ignores the abstraction layer that makes WordPress manageable. Unless you are building a custom plugin that needs to manipulate the menu structure at a low level for performance reasons (and even then, it is rarely necessary), sticking to the API is the professional standard.
Handling Edge Cases
If your menu items are still blank after confirming assignment, check for parent-child relationships. wp_get_nav_menu_items() returns all items by default. If you have a nested menu structure, ensure you aren't filtering the output incorrectly. You can use the depth argument to limit how many levels of sub-menus are returned:
$menu_items = wp_get_nav_menu_items( 'primary', array( 'depth' => 2 ) );
Additionally, be aware that wp_get_nav_menu_items() requires the theme location to be valid. If you pass a string like 'home' or 'footer' and those locations aren't registered in your theme's functions.php, the function will return an empty array immediately, regardless of whether menus exist with those names. Always verify that the location name matches exactly what is defined in register_nav_menus().