Radical Design Course by Jack McDade

From the creator of Statamic

Learn how to make your websites standout and be remembered.

Just exceptional. Thank you so much, Jack, you smashed it.

— Hugo, Developer

Nav Tag

The nav tags are designed to help your users navigate through your hierarchy of navigations and collections.


The various Nav tags work together to allow you to easily traverse your content upways and downways, sideways, slantways, longways, backways, squareways, frontways, and any other ways that you can think of.

This tag is designed to be used for top-level and multi-level navs.

The nav tag supports both navigations or multi-depth collections.

You specify what kind you need by using the second tag part:

// The "links" nav
{{ nav:links }} ... {{ /nav:links }}
// The "pages" collection
{{ nav:collection:pages }} ... {{ /nav:collection:pages }}

If you use the tag on it's own without a second part, it will assume you want the pages collection. That's a super common thing to do, and the statamic/statamic repo comes bundled with it.

// Also the "pages" collection
{{ nav }} ... {{ /nav }}

You can also specify the navigation using the handle parameter:

{{ nav handle="links" }} ... {{ /nav }}

Basic Example

A single level nav, much like something you'd have at the top of your site, can be built by looping through all the items in the nav and using their title and url variables in your HTML. Add a "current" state by checking for is_current and is_parent, and you're probably good to go.

{{ nav include_home="true" }}
<a href="{{ url }}"{{ if is_current || is_parent }} class="current"{{ /if }}>
{{ title }}
{{ /nav }}

Show the children of the current page

Hot Tip!

A simpler way is to use the children tag for this.

Use the uri to get the children of the current page.

{{ nav :from="uri" }}
{{ unless no_results }}
<a href="{{ url }}">{{ title }}</a>
{{ /unless }}
{{ /nav }}

Multi-level Nav Example Recursion

Building an infinitely deep nav is possible by using recursion.

{{ nav :from="segment_1" }}
<a href="{{ url }}"{{ if is_current || is_parent }} class="on"{{ /if }}>{{ title }}</a>
{{ if is_current || is_parent }}
{{ if children }}
<ul>{{ *recursive children* }}</ul>
{{ /if }}
{{ /if }}
{{ /nav }}

The {{ *recursive children* }} tag will repeat the contents of the entire {{ nav }} tag using child elements, if they exist. As long as there are children to display, and we’re still on either the current or parent page of those children, the nav tag will traverse deeper. If your scoped variables have trouble making it through to the next recursion, you can glue them to children like this: {{ *recursive children:my_scoped_variable* }}.

Take the time to wrap your brain around this concept and learn to wield it and a powerful Jedi will you be.

Hot Tip!

The Jedi have blessed us all with even more recursive nav examples, so that you may have the high ground next time you're fighting that losing nav battle on Mustafar.


You may improve performance of the nav tag in two ways:

  1. Set the max_depth parameter appropriately.
    If you only need one level, set max_depth="1".
  2. Select the fields that you'll be using.
    If you're only going to be using {{ title }} and {{ url }} in the loop, set select="title|url".




The navigation or collection to use (e.g. {{ nav handle="collection::my_pages_collection_handle" }}). Not necessary if you're using the shorthand tag (e.g. {{ nav:links }})



Specify the URI of the entry to be used as the starting point for your navigation. If unspecified, it'll start from the top. Note: this parameter is only supported for orderable collections.


boolean *false*

Unpublished content is, by it's very nature, unpublished. That is, unless you show it by turning on this parameter.


boolean *false*

You can choose to turn off the home page in the tree, opting to start the crumbs from the first level nav item. Doesn't do anything if you're using the from parameter.



This limits how deep the tag will render. If you are using recursion, this could be useful to stop at a certain point. It also helps with performance. By default there is no max.



Limits the fields that will be made available to the tag. Selecting fewer fields will improve performance. By default all variables will be selected. See performance.


Variable Type Description



Whether or not the page is published.



Whether or not the page is in fact a page. If you are using the entries parameter to show entries, a "page" may potentially be an entry.



The inverse of is_page. Outputs whether the "page" is an entry.



Whether the current page has entries mounted to it.



An array of child pages. Use this as a tag pair to iterate over any child pages.



An array containing the current page's parent. Use this as a tag pair to output variables from the parent's page data.



Whether the current page is a parent of the URL being viewed. Useful for outputting active states.



Whether the current page is the URL being viewed. Also useful for outputting active states.



Whether the current nav URL is an external link . Useful for outputting target=_"blank" in menu templates.



The depth of the page within the nav structure.

page data


Each page being iterated has access to all the variables inside that page. This includes things like title, content, etc.

*recursive children*


Recursively output the entire contents of the nav tag pair.

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →