Radical Design Course by Jack McDade

From the creator of Statamic

Learn how to make your websites standout and be remembered.

This course is the most refreshing take on teaching design that I've come across.

— Mikaël Sévigny, Developer

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>

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.

<ul>
{{ nav :from="uri" }}
{{ unless no_results }}
<li>
<a href="{{ url }}">{{ title }}</a>
</li>
{{ /unless }}
{{ /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>

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.

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

handle

string

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 }})

from

string

The starting point for your navigation. If unspecified, it'll start from the top. Note: this parameter is only supported for orderable collections.

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

max_depth

int

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.

select

array

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.

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.

is_external

boolean

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

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.

Docs feedback

Submit improvements, related content, or suggestions through Github.

Betterify this page →