Nav Tag

Overview

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.

Navs or Collections

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 "links" nav
<s:nav:links>
  ...
</s:nav:links>

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

// The "pages" collection
<s:nav:collection:pages>
  ...
</s: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 }}

// Also the "pages" collection
<s:nav>
  ...
</s:nav>

You can also specify the navigation using the handle parameter:

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

<s:nav
  handle="links"
>
  ...
</s: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.

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

<ul>
  <s:nav include_home="true">
    <li>
      <a
        href="{{ $url }}"
        @if ($is_current || $is_parent) class="current" @endif
      >
        {{ $title }}
      </a>
    </li>
  </s:nav>
</ul>

Show the children of the current page

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

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

<ul>
  <s:nav :from="uri" as="pages">
    @foreach ($pages as $page)
      <li>
        <a href="{{ $page['url'] }}">{{ $page['title'] }}</a>
      </li>
    @endforeach
  </s:nav>
</ul>

Multi-level Nav Example Recursion

Building an infinitely deep nav is possible by using recursion.

<ul>
   {{ nav :from="segment_1" }}
      <li>
         <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 }}
      </li>
   {{ /nav }}
</ul>

<ul>
   <s:nav :from="$segment_1">
      <li>
         <a
           href="{{ $url }}"
           @if ($is_current || $is_parent) class="current" @endif
         >
           {{ $title }}
         </a>
         @if ($is_current || $is_parent)
            @if (count($children) > 0)
               <ul>@recursive_children</ul>
            @endif
         @endif
      </li>
   </s:nav>
</ul>

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.

Performance

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".

Parameters

Variables