Nav

The nav tags are designed to help your users navigate through your hierarchy of pages. They 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.


Recursion

It’s possible to use recursive tags for semi-automatically creating deeply-nested lists of links as your navigations. A sample set-up looks something like this:

<ul>
   {{ nav from="/{segment_1}" max_depth="2" }}
      <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. This means that 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* }}.

It’s an admittedly weird concept, and might take some fiddling with to truly understand, but is very powerful when fully understood. Take the time. Learn to wield it. A powerful Jedi will you be.

Children

If you want to take more control over your child menu, you can just loop through the children array within your menu, instead of repeating the contents of the child elements with {{ *recursive children* }}.

{{ if is_current || is_parent }}
  {{ if children }}
     <ul>
      {{ children }}
        <li><a href="{{ url }}">{{ title }}</a></li>
      {{ /children }}
     </ul>
  {{ /if }}
{{ /if }}

Hidden Pages

A common use-case for navigation is to make some pages “hidden”, which means to hide them from the nav, but keep them available when accessed directly.

Note: In Statamic v1, you should set the status to hidden or prefix the filename with an underscore. In v2, this method has been removed in favor of the following workflow.

  1. Add a field to your page fieldset that’ll be used to indicate a “hidden” page:

    fields:
      is_hidden:  # the field name can be whatever you want
        type: toggle
        display: Hide from navigation
    
  2. In your nav tag, use the conditions syntax to remove any hidden pages:

    {{ nav from="/" is_hidden:isnt="true" }}
       ...
    {{ /nav }}
    

    This is saying, only show pages where the is_hidden field isn’t set to true. That will leave you with unhidden pages. Remember, the field can be named whatever you want.


Parameters

from

string

The starting point for your navigation. If unspecified, it'll use the current URI.

max_depth

integer 2*

The maximum number of subdirectory levels to traverse, letting you build a multi-level nav.

limit

integer

Limit the total items returned.

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_entries

boolean false

Whether entries mounted under a page should be included as part of the navigation.

sort

string

The field by which the pages will be sorted. For example, specify title to sort alphabetically by the title field.

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.

include_root

boolean false

You can choose to turn off the root page (whatever you've provided to the from parameter) in the tree, opting to start the crumbs from the first level nav item. (When from is the root, this is the same as the include_home parameter)

exclude

string|array

A single URL, or a list of multiple pipe-separated URLs, to be excluded.

filter

wizardry

Filter the tree by using a special conditions syntax, the same as the Collections tag. View the available conditions.

supplement_taxonomies

boolean true

By default, Statamic will convert taxonomy term values into actual term objects that you may loop through. This has some performance overhead, so you may disable this for a speed boost if taxonomies aren't necessary.


Variables

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.

Last modified on November 19, 2019