Nav Tag

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

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.

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.

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

Multi-level Nav Example Recursion

Build 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>

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.

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.

Parameters

handle string

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

from string

The starting point for your navigation. If unspecified, it'll start from the top.

show_unpublished boolean *false*

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

include_home 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 paramter.

Variables

Variable Type Description

is_published

boolean

Whether or not the page is published.

is_page

boolean

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.

is_entry

boolean

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

has_entries

boolean

Whether the current page has entries mounted to it.

children

array

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

parent

array

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

is_parent

boolean

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

is_current

boolean

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

depth

integer

The depth of the page within the nav structure.

page data

mixed

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

recursive children

wizardry

Recursively output the entire contents of the nav tag pair.

Betterify this page on Github!