Node Queries#

You can fetch nodes in your templates or PHP code using node queries.

{# Create a new node query #}
{% set myQuery = craft.navigation.nodes() %}

// Create a new node query
$myQuery = \verbb\navigation\elements\Node::find();

Once you’ve created a node query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Node objects will be returned.

See Introduction to Element Queries (opens new window) in the Craft docs to learn about how element queries work.

Example#

We can display nodes for a given level by doing the following:

Create a node query with craft.navigation.nodes().
Set the level, and limit parameters on it.
Fetch all nodes with .all() and output.
Loop through the nodes using a for (opens new window) tag to output the contents.

{# Create a nodes query with the 'level', and 'limit' parameters #}
{% set nodesQuery = craft.navigation.nodes()
    .level(1)
    .limit(10)%}

{# Fetch the Comments #}
{% set nodes = nodesQuery.all() %}

{# Display their contents #}
{% for node in nodes %}
    <p>{{ node.node }}</p>
{% endfor %}

Parameters#

Node queries support the following parameters:

`ancestorDist`#

Narrows the query results to only nodes that are up to a certain distance away from the node specified by ancestorOf.

{# Fetch nodes above this one #}
{% set nodes = craft.navigation.nodes()
    .ancestorOf(node)
    .ancestorDist(3)
    .all() %}

// Fetch nodes above this one
$nodes = \verbb\navigation\elements\Node::find()
    ->ancestorOf($node)
    ->ancestorDist(3)
    ->all();

`ancestorOf`#

Narrows the query results to only nodes that are ancestors of another node.

Possible values include:

Value	Fetches nodes…
`1`	above the node with an ID of 1.
a Node object	above the node represented by the object.

{# Fetch nodes above this one #}
{% set nodes = craft.navigation.nodes()
    .ancestorOf(node)
    .all() %}

// Fetch nodes above this one
$nodes = \verbb\navigation\elements\Node::find()
    ->ancestorOf($node)
    ->all();

This can be combined with ancestorDist if you want to limit how far away the ancestor nodes can be.

`anyStatus`#

Clears out the status() (opens new window) and enabledForSite() (opens new window) parameters.

{# Fetch all nodes, regardless of status #}
{% set nodes = craft.navigation.nodes()
    .anyStatus()
    .all() %}

// Fetch all nodes, regardless of status
$nodes = \verbb\navigation\elements\Node::find()
    ->anyStatus()
    ->all();

`asArray`#

Causes the query to return matching nodes as arrays of data, rather than Node objects.

{# Fetch nodes as arrays #}
{% set nodes = craft.navigation.nodes()
    .asArray()
    .all() %}

// Fetch nodes as arrays
$nodes = \verbb\navigation\elements\Node::find()
    ->asArray()
    ->all();

`dateCreated`#

Narrows the query results based on the nodes’ creation dates.

Possible values include:

Value	Fetches nodes…
`'>= 2018-04-01'`	that were created on or after 2018-04-01.
`'< 2018-05-01'`	that were created before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were created between 2018-04-01 and 2018-05-01.

{# Fetch nodes created last month #}
{% set start = date('first day of last month') | atom %}
{% set end = date('first day of this month') | atom %}

{% set nodes = craft.navigation.nodes()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

// Fetch nodes created last month
$start = new \DateTime('first day of next month')->format(\DateTime::ATOM);
$end = new \DateTime('first day of this month')->format(\DateTime::ATOM);

$nodes = \verbb\navigation\elements\Node::find()
    ->dateCreated(['and', ">= {$start}", "< {$end}"])
    ->all();

`dateUpdated`#

Narrows the query results based on the nodes’ last-updated dates.

Possible values include:

Value	Fetches nodes…
`'>= 2018-04-01'`	that were updated on or after 2018-04-01.
`'< 2018-05-01'`	that were updated before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were updated between 2018-04-01 and 2018-05-01.

{# Fetch nodes updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set nodes = craft.navigation.nodes()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

// Fetch nodes updated in the last week
$lastWeek = new \DateTime('1 week ago')->format(\DateTime::ATOM);

$nodes = \verbb\navigation\elements\Node::find()
    ->dateUpdated(">= {$lastWeek}")
    ->all();

`descendantDist`#

Narrows the query results to only nodes that are up to a certain distance away from the node specified by descendantOf.

{# Fetch nodes below this one #}
{% set nodes = craft.navigation.nodes()
    .descendantOf(node)
    .descendantDist(3)
    .all() %}

// Fetch nodes below this one
$nodes = \verbb\navigation\elements\Node::find()
    ->descendantOf($node)
    ->descendantDist(3)
    ->all();

`descendantOf`#

Narrows the query results to only nodes that are descendants of another node.

Possible values include:

Value	Fetches nodes…
`1`	below the node with an ID of 1.
a Node object	below the node represented by the object.

{# Fetch nodes below this one #}
{% set nodes = craft.navigation.nodes()
    .descendantOf(node)
    .all() %}

// Fetch nodes below this one
$nodes = \verbb\navigation\elements\Node::find()
    ->descendantOf($node)
    ->all();

This can be combined with descendantDist if you want to limit how far away the descendant nodes can be.

`enabledForSite`#

Narrows the query results based on whether the nodes are enabled in the site they’re being queried in, per the site parameter.

Possible values include:

Value	Fetches nodes…
`true` (default)	that are enabled in the site.
`false`	whether they are enabled or not in the site.

{# Fetch all nodes, including ones disabled for this site #}
{% set nodes = craft.navigation.nodes()
    .enabledForSite(false)
    .all() %}

// Fetch all nodes, including ones disabled for this site
$nodes = \verbb\navigation\elements\Node::find()
    ->enabledForSite(false)
    ->all();

`fixedOrder`#

Causes the query results to be returned in the order specified by id.

{# Fetch nodes in a specific order #}
{% set nodes = craft.navigation.nodes()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

// Fetch nodes in a specific order
$nodes = \verbb\navigation\elements\Node::find()
    ->id([1, 2, 3, 4, 5])
    ->fixedOrder()
    ->all();

`hasDescendants`#

Narrows the query results based on whether the nodes have any descendants.

(This has the opposite effect of calling leaves.)

{# Fetch nodes that have descendants #}
{% set nodes = craft.navigation.nodes()
    .hasDescendants()
    .all() %}

// Fetch nodes that have descendants
$nodes = \verbb\navigation\elements\Node::find()
    ->hasDescendants()
    ->all();

`hasUrl`#

Narrows the query results based on whether the nodes have a URL.

{# Fetch nodes that have descendants #}
{% set nodes = craft.navigation.nodes()
    .hasUrl()
    .all() %}

// Fetch nodes that have descendants
$nodes = \verbb\navigation\elements\Node::find()
    ->hasUrl()
    ->all();

`id`#

Narrows the query results based on the nodes’ IDs.

Possible values include:

Value	Fetches nodes…
`1`	with an ID of 1.
`'not 1'`	not with an ID of 1.
`[1, 2]`	with an ID of 1 or 2.
`['not', 1, 2]`	not with an ID of 1 or 2.

{# Fetch the node by its ID #}
{% set node = craft.navigation.nodes()
    .id(1)
    .one() %}

// Fetch the node by its ID
$node = \verbb\navigation\elements\Node::find()
    ->id(1)
    ->one();

This can be combined with fixedOrder if you want the results to be returned in a specific order.

`inReverse`#

Causes the query results to be returned in reverse order.

{# Fetch nodes in reverse #}
{% set nodes = craft.navigation.nodes()
    .inReverse()
    .all() %}

// Fetch nodes in reverse
$nodes = \verbb\navigation\elements\Node::find()
    ->inReverse()
    ->all();

`leaves`#

Narrows the query results based on whether the nodes are “leaves” (nodes with no descendants).

(This has the opposite effect of calling hasDescendants.)

{# Fetch nodes that have no descendants #}
{% set nodes = craft.navigation.nodes()
    .leaves()
    .all() %}

// Fetch nodes that have no descendants
$nodes = \verbb\navigation\elements\Node::find()
    ->leaves()
    ->all();

`level`#

Narrows the query results based on the nodes’ level within the structure.

Possible values include:

Value	Fetches nodes…
`1`	with a level of 1.
`'not 1'`	not with a level of 1.
`'>= 3'`	with a level greater than or equal to 3.
`[1, 2]`	with a level of 1 or 2
`['not', 1, 2]`	not with level of 1 or 2.

{# Fetch nodes positioned at level 3 or above #}
{% set nodes = craft.navigation.nodes()
    .level('>= 3')
    .all() %}

// Fetch nodes positioned at level 3 or above
$nodes = \verbb\navigation\elements\Node::find()
    ->level('>= 3')
    ->all();

`limit`#

Determines the number of nodes that should be returned.

{# Fetch up to 10 nodes  #}
{% set nodes = craft.navigation.nodes()
    .limit(10)
    .all() %}

// Fetch up to 10 nodes
$nodes = \verbb\navigation\elements\Node::find()
    ->limit(10)
    ->all();

`nextSiblingOf`#

Narrows the query results to only the node that comes immediately after another node.

Possible values include:

Value	Fetches the node…
`1`	after the node with an ID of 1.
a Node object	after the node represented by the object.

{# Fetch the next node #}
{% set node = craft.navigation.nodes()
    .nextSiblingOf(node)
    .one() %}

// Fetch the next node
$node = \verbb\navigation\elements\Node::find()
    ->nextSiblingOf($node)
    ->one();

`offset`#

Determines how many nodes should be skipped in the results.

{# Fetch all nodes except for the first 3 #}
{% set nodes = craft.navigation.nodes()
    .offset(3)
    .all() %}

// Fetch all nodes except for the first 3
$nodes = \verbb\navigation\elements\Node::find()
    ->offset(3)
    ->all();

`orderBy`#

Determines the order that the nodes should be returned in.

{# Fetch all nodes in order of date created #}
{% set nodes = craft.navigation.nodes()
    .orderBy('elements.dateCreated asc')
    .all() %}

// Fetch all nodes in order of date created
$nodes = \verbb\navigation\elements\Node::find()
    ->orderBy('elements.dateCreated asc')
    ->all();

`positionedAfter`#

Narrows the query results to only nodes that are positioned after another node.

Possible values include:

Value	Fetches nodes…
`1`	after the node with an ID of 1.
a Node object	after the node represented by the object.

{# Fetch nodes after this one #}
{% set nodes = craft.navigation.nodes()
    .positionedAfter(node)
    .all() %}

// Fetch nodes after this one
$nodes = \verbb\navigation\elements\Node::find()
    ->positionedAfter($node)
    ->all();

`positionedBefore`#

Narrows the query results to only nodes that are positioned before another node.

Possible values include:

Value	Fetches nodes…
`1`	before the node with an ID of 1.
a Node object	before the node represented by the object.

{# Fetch nodes before this one #}
{% set nodes = craft.navigation.nodes()
    .positionedBefore(node)
    .all() %}

// Fetch nodes before this one
$nodes = \verbb\navigation\elements\Node::find()
    ->positionedBefore($node)
    ->all();

`prevSiblingOf`#

Narrows the query results to only the node that comes immediately before another node.

Possible values include:

Value	Fetches the node…
`1`	before the node with an ID of 1.
a Node object	before the node represented by the object.

{# Fetch the previous node #}
{% set node = craft.navigation.nodes()
    .prevSiblingOf(node)
    .one() %}

// Fetch the previous node
$node = \verbb\navigation\elements\Node::find()
    ->prevSiblingOf($node)
    ->one();

`siblingOf`#

Narrows the query results to only nodes that are siblings of another node.

Possible values include:

Value	Fetches nodes…
`1`	beside the node with an ID of 1.
a Node object	beside the node represented by the object.

{# Fetch nodes beside this one #}
{% set nodes = craft.navigation.nodes()
    .siblingOf(node)
    .all() %}

// Fetch nodes beside this one
$nodes = \verbb\navigation\elements\Node::find()
    ->siblingOf($node)
    ->all();

`site`#

Determines which site the nodes should be queried in.

The current site will be used by default.

Possible values include:

Value	Fetches nodes…
`'foo'`	from the site with a handle of `foo`.
a `\craft\elements\db\Site` object	from the site represented by the object.

{# Fetch nodes from the Foo site #}
{% set nodes = craft.navigation.nodes()
    .site('foo')
    .all() %}

// Fetch nodes from the Foo site
$nodes = \verbb\navigation\elements\Node::find()
    ->site('foo')
    ->all();

`siteId`#

Determines which site the nodes should be queried in, per the site’s ID.

The current site will be used by default.

{# Fetch nodes from the site with an ID of 1 #}
{% set nodes = craft.navigation.nodes()
    .siteId(1)
    .all() %}

// Fetch nodes from the site with an ID of 1
$nodes = \verbb\navigation\elements\Node::find()
    ->siteId(1)
    ->all();

`status`#

Narrows the query results based on the nodes’ statuses.

Possible values include:

Value	Fetches nodes…
`'enabled'` (default)	that are enabled.
`'disabled'`	that are disabled.

{# Fetch disabled nodes #}
{% set nodes = craft.navigation.nodes()
    .status('disabled')
    .all() %}

// Fetch disabled nodes
$nodes = \verbb\navigation\elements\Node::find()
    ->status('disabled')
    ->all();

`uid`#

Narrows the query results based on the nodes’ UIDs.

{# Fetch the node by its UID #}
{% set node = craft.navigation.nodes()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

// Fetch the node by its UID
$node = \verbb\navigation\elements\Node::find()
    ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    ->one();

Previous ← Eager-Loading Next Node →

Get Started

Feature Tour

Template Guides

Getting Elements

Developers

Node Queries#

Example#

Parameters#

`ancestorDist`#

`ancestorOf`#

`anyStatus`#

`asArray`#

`dateCreated`#

`dateUpdated`#

`descendantDist`#

`descendantOf`#

`enabledForSite`#

`fixedOrder`#

`hasDescendants`#

`hasUrl`#

`id`#

`inReverse`#

`leaves`#

`level`#

`limit`#

`nextSiblingOf`#

`offset`#

`orderBy`#

`positionedAfter`#

`positionedBefore`#

`prevSiblingOf`#

`siblingOf`#

`site`#

`siteId`#

`status`#

`uid`#

On this page

Get Started

Feature Tour

Template Guides

Getting Elements

Developers

​Node Queries#

​Example#

​Parameters#

​ancestorDist#

​ancestorOf#

​anyStatus#

​asArray#

​dateCreated#

​dateUpdated#

​descendantDist#

​descendantOf#

​enabledForSite#

​fixedOrder#

​hasDescendants#

​hasUrl#

​id#

​inReverse#

​leaves#

​level#

​limit#

​nextSiblingOf#

​offset#

​orderBy#

​positionedAfter#

​positionedBefore#

​prevSiblingOf#

​siblingOf#

​site#

​siteId#

​status#

​uid#

On this page

Node Queries#

Example#

Parameters#

`ancestorDist`#

`ancestorOf`#

`anyStatus`#

`asArray`#

`dateCreated`#

`dateUpdated`#

`descendantDist`#

`descendantOf`#

`enabledForSite`#

`fixedOrder`#

`hasDescendants`#

`hasUrl`#

`id`#

`inReverse`#

`leaves`#

`level`#

`limit`#

`nextSiblingOf`#

`offset`#

`orderBy`#

`positionedAfter`#

`positionedBefore`#

`prevSiblingOf`#

`siblingOf`#

`site`#

`siteId`#

`status`#

`uid`#