Verbb
You are viewing beta documentation for Navigation 4.x.
GraphQL

Query Nodes

Navigation exposes nodes via GraphQL for headless front-ends. Be sure to read Craft's GraphQL support (opens new window) for general schema and token setup.

Example

{
  navigationNodes(menuHandle: "mainMenu", level: 1) {
    title
    url
    current
    active
    hasActiveChild
    children {
      title
      url
    }
  }
}

Use the singular navigationNode query to fetch one node by ID or UID.

In addition to standard Craft element query arguments (opens new window), node queries support:

ArgumentDescription
menuHandleMenu handle
menuIdMenu ID
typeNode type class name(s)
withLinkedElementsBatch-load linked Craft elements (disables tree cache)
withNodeHierarchyWire parent/child in memory (null = auto on front-end)
withNavigationCacheOpt in when cache mode is Manual
withMenuBatch-load parent Menu elements (disables tree cache)
withProjectedChildrenInclude Dynamic projections; false to skip

Site and language

  • site / siteId select which node variant to return (per-site titles, URLs, enabled state).
  • For element-backed nodes, linkedElementSiteId (per node-site row) selects which locale of the linked element supplies the URL — independent of the node's siteId.

In multisite setups, pass explicit site / siteId when the requested site is not the primary site. The language field on each node reflects the site's language, not a separate filter dimension.

Headless consumers should use the same site context as entry queries so URLs and enabled state match the front-end.

Each menu with a field layout can expose a {handle}_Menu GraphQL type for menu-level custom fields.

Projected nodes

Dynamic children return as ProjectedNavigationNode with isProjected: true. See Projected Node.

Node interface

Node results implement NodeInterface with fields including menuId, menuHandle, menuName, elementId, url, urlSuffix, nodeUri, type, classes, customAttributes, newWindow, children, parent, and element (when hydrated).

For full Twig parity, see Node and Node Queries.

Last updated: July 3, 2026, 1:22:00 PM
Previous Node Queries Next Context & Breadcrumbs