Navigation Queries

Query WordPress navigation menus for headers, footers, and site navigation structures.

What This Guide Covers

Navigation menus are essential for site structure and user experience - header menus, footer links, sidebar navigation, and custom menu areas. This guide shows you how to query WordPress navigation menus using Builderius GraphQL for any navigation scenario.

You'll learn how to:

• Get specific navigation menus by name or slug
• Access the primary navigation menu automatically
• Query menu items with hierarchical structures
• Access custom menu item fields from ACF and MetaBox
• Build complex multi-level navigation with unlimited depth
• Handle conditional menu display and external link detection

Query Single Navigation Menu

Primary Menu

Get the primary navigation menu (WordPress theme automatically sets the primary menu):

{
  primary_nav_menu {
    items {
      ID
      title
      url
      classes
      target
    }
  }
}

Specific Menu

Get a menu by ID, name, or slug:

{
  # Query by menu ID (default identifier)
  nav_menu(identifier: "ID", value: 123) {     # Int - Menu ID number
    items {
      title
      url
    }
  }
  
  # Query by menu slug  
  nav_menu(identifier: "slug", value: "main-menu") {     # String - Menu slug
    items {
      title
      url
    }
  }
  
  # Query by menu name
  nav_menu(identifier: "name", value: "Main Navigation") {     # String - Menu name
    items {
      title
      url
    }
  }
}

Complete Navigation Fields Reference

Here's what's available when querying navigation menus - all standard WordPress menu fields plus custom field integrations:

{
  # Single menu by identifier
  nav_menu(identifier: "slug", value: "main-menu") {
    # NavMenu Fields
    name
    term_id
    slug
    count
    
    # Menu Items
    items {
      # Basic Fields
      ID
      title
      url
      description
      classes
      target
      attr_title
      db_id
      
      # Menu Structure
      menu_item_parent
      post_parent
      post_title
      
      # Link Details
      object
      object_id
      type
      type_label
      xfn
      
      # Relationships
      parent {
        ID
        title
        url
      }
      children {
        ID
        title
        url
      } 
      
      # Native WordPress Meta Fields
      custom_class: meta_value(key: "_menu_item_classes")
      custom_target: meta_value(key: "_menu_item_target")
      
      # All Meta Fields (returns array)
      meta {
        key
        value
      }
      
      # ACF Fields
      menu_icon: acf_value(name: "menu_icon")
      highlight_item: acf_value(name: "highlight_item")
      mega_menu_content: acf_value(name: "mega_menu_content")
      custom_color: acf_value(name: "custom_color")
      badge_text: acf_value(name: "badge_text")
      
      # MetaBox Fields (Menu Item Level)
      item_priority: metabox_value(field_id: "item_priority")
      display_settings: metabox_value(field_id: "display_settings")
      
      # PHP Function Output
      post_meta: php_function_output(
        function: "get_post_meta"
        arguments: ["{{ID}}", "custom_key", true]
      )
    }
  }
  
  # Primary navigation menu (no identifier needed)
  primary_nav_menu {
    name
    term_id
    slug
    count
    items {
      # Same NavMenuItem fields as above
      title
      url
      target
    }
  }
  
  # All navigation menus
  nav_menus {
    name
    term_id
    slug
    count
    items {
      # Same NavMenuItem fields as above
      title
      url
    }
  }
}

Basic Navigation Loops

Primary Menu

Get the primary navigation menu:

{
  primary_nav_menu {
    name
    slug
    count
    items {
      ID
      title
      url
      classes
      target
      description
    }
  }
}

Specific Menu

Get a specific menu by name:

{
  nav_menu(identifier: "name", value: "Header Menu") {
    name
    slug
    count
    items {
      ID
      title
      url
      classes
      target
      description
    }
  }
}

Custom Navigation Queries

Get specific navigation menus Pro feature for different areas of your site with custom filtering and display options.

Header Menu

Header navigation with dropdown support:

{
  nav_menu(identifier: "slug", value: "header-menu") {
    items {
      ID
      title
      url
      classes
      target
      description
      # Check for dropdown items
      has_children: expression_result(
        expression: "count(children) > 0"
      )
      children @recursive {
        ID
        title
        url
        classes
        target
      }
    }
  }
}

Footer Menu

Footer navigation with simple flat structure:

{
  nav_menu(identifier: "name", value: "Footer Links") {
    items {
      ID
      title
      url
      target
      # Check if external link
      is_external: expression_result(
        expression: "includes(url, 'http') && !includes(url, site_url())"
      )
    }
  }
}

Mega Menu

Mega menu with custom fields and complex structure:

{
  nav_menu(identifier: "slug", value: "mega-menu") {
    items {
      ID
      title
      url
      classes
      target
      description
      # ACF fields for mega menu
      menu_icon: acf_value(name: "menu_icon")
      mega_menu_content: acf_value(name: "mega_menu_content")
      highlight_item: acf_value(name: "highlight_item")
      column_width: acf_value(name: "column_width")
      # Nested structure
      children @recursive {
        ID
        title
        url
        description
        menu_icon: acf_value(name: "menu_icon")
      }
    }
  }
}

Hierarchical Relationships

Navigate between menu items using parent-child relationships and build complex nested structures.

Menu Levels

Complete menu hierarchy with configurable nesting levels:

{
  nav_menu(identifier: "slug", value: "main-navigation") {
    items {
      ID
      title
      url
      classes
      target
      description
      # Default 10 levels deep
      children @recursive {
        ID
        title
        url
        classes
        target
        menu_item_parent
      }
    }
  }
}

Or limit the depth for better performance:

{
  nav_menu(identifier: "slug", value: "main-navigation") {
    items {
      ID
      title
      url
      classes
      target
      # Custom depth limit - only 3 levels deep
      children @recursive(depth: 3) {
        ID
        title
        url
        classes
        target
        menu_item_parent
      }
    }
  }
}

Recursive Structure

Organize menu by specific depth levels:

{
  nav_menu(identifier: "slug", value: "main-navigation") {
    items {
      ID
      title
      url
      classes
      # Top level items
      level_one_children: children {
        ID
        title
        url
        # Second level items  
        level_two_children: children {
          ID
          title
          url
          # Third level items
          level_three_children: children {
            ID
            title
            url
          }
        }
      }
    }
  }
}

Performance Tips

Optimize your navigation queries for better performance and faster page loads.

Limit Fields

Only fetch the menu item fields you actually need:

{
  primary_nav_menu {
    items {
      title                          # Only essential fields
      url
      target
      # Skip unused fields like description, classes, etc.
      children @recursive {
        title                        # Same limited fields for children
        url
        target
      }
    }
  }
}

Efficient Recursion

Control recursion depth when you don't need unlimited levels:

{
  nav_menu(identifier: "slug", value: "simple-menu") {
    items {
      title
      url
      # Limit to 2 levels deep for performance
      children @recursive(depth: 2) {
        title
        url
        classes
      }
    }
  }
}