We use cookies to make your viewing experience better. By accepting you consent, you agree to our Cookie policy

Improve your Craft CMS skills

A User Guide For The Craft CMS Navigation Plugin

10 min read
Ovoby Print

Building a fully-featured, user-friendly navigation is crucial for any Craft CMS site. But wrestling with menus and complex mega navs can be a headache. This guide will save you pain by clearly walking through how to master menus with Craft's robust Navigation plugin. From setup and configuration to outputting flexible, customized menus, you'll get actionable tips to level up your navigation game.

The Craft CMS Navigation plugin provides powerful tools for building flexible, customizable menus. By leveraging the plugin's templating, settings, and JavaScript hooks you can create robust multi-level navigations. Careful planning along with CSS and JS customization will enable you to output mobile-friendly mega menus that engage users and boost SEO.

Installing and Activating the Plugin

Downloading the Plugin

There are a couple of ways you can get your hands on the Craft CMS Navigation plugin. The official website will have the latest stable release available to download, just head to the plugins section and grab the zip file. GitHub is also a good place to find the source code if you want to tinker with the latest dev version.

When installing a Craft plugin, it's generally best practice to use a trusted source like the official website or GitHub repo. That way you can be confident you're getting the authentic package, not some dodgy altered copy. Safety first!

Once you've downloaded the zip, it's a piece of cake to upload and install in your Craft control panel. Just navigate to Settings > Plugins, hit the "Upload plugin" button, select your zip and you're off to the races. Total breeze.

Using Composer vs Plugin Store

The Craft plugin store is hands down the most convenient way to install Craft CMS plugins. You can browse, purchase and install everything seamlessly from within the control panel. Major time saver.

Composer, on the other hand, requires a bit more technical know-how. You'll need shell access and an understanding of the command line. For developers, Composer may be preferred as it allows granular control over dependencies and versions.

The plugin store wins for simplicity and ease of use. But Composer is invaluable for handling complex project dependencies, especially when using multiple plugins together.

So if you're not a dev type and just want quick, no fuss installation - go with the plugin store. For those comfortable on the command line, Composer gives you more advanced options. Either way, you've got flexible choices to suit your skills and needs.

Enabling and Configuring

Once the Navigation plugin files are uploaded, either via Composer or zip, you'll need to enable it before use. This takes just a few clicks in the Craft control panel.

Go to Settings > Plugins and flip the switch to "on" next to the Navigation plugin. And that's it activated! The plugin will now be available to use across your site.

You may also want to check out the plugin settings page to set up any configuration options. For navigation, this may include setting the max depth of menus, custom labels, and adding custom navigation templates.

The settings page lets you tweak things to your exact needs. Don't forget to hit "save" after making any changes!

It's also worth noting that some plugins will require certain Craft/PHP versions, so always check the requirements before installing. Activation can fail if the environment doesn't meet the plugin's dependencies.

But as long as you've got a supported Craft build and the plugin is enabled, you'll now be able to start building navigation in your templates. Get ready to take your site's menus to the next level!

Creating Navigation Menus

Adding Your First Menu

Ready to start building your first navigation menu with the Craft plugin? It's simple to spin up a new menu right from the control panel.

First, navigate to the Navigation section. Here you'll see any existing menus you've already created. To add a shiny new one, just click the handy "New menu" button.

You'll get a form to name your menu and pick a handle. Go descriptive - something like "Main Navigation" works well. The handle will be the reference in your templates, so make it lowercase, no spaces.

Hit save and boom! Your fresh new menu is ready to start populating. The control panel makes it super easy to put together your first menu in no time.

Pro tip: Create specific menus for different areas, like a footer menu separate from main nav. Keeping things modular gives more flexibility as your site grows.

Structuring the Menu

Now you've got an empty menu container ready to fill up. This is where you can start constructing the structure and hierarchy for your mega nav.

Within the menu edit screen, you'll see options to create menu items, nest items, and drag-drop to arrange order and levels. Really intuitive.

Think about the multi-level structure you want. Top level pages across the top, with children nesting below. Use the indent and outdent buttons to create the groups and levels.

For mega menus with lots of nesting, it helps to sketch it out first for the ideal hierarchy. But don't be afraid to tweak as you go - the beauty of digital menus!

Use the reorder handles to get the navigation flow in the optimal sequence. Typically, most important links up top. Parents before children. Logical stuff.

Populating the Menu

Now for the fun part - filling the menu with actual links and pages. You've got a few options for content sources here.

The simplest is to pull pages and entries directly from Craft. Just start typing a title and matching pages/entries will auto-populate. This seamlessly syncs updates.

You can also create custom URLs as menu items, like external links or anchors. Just enable the Custom URL option and type in the target.

For mega menus, you'll likely want a combo of both. Pull in key site pages/entries, then sprinkle in custom links for things like social, email signup, etc.

Get creative with what you populate the menu with to really maximize its value for users. And customize the labels however you like - they don't have to match the entry title. Go wild!

With those robust and flexible options, you'll have your navigation menu fleshed out in no time. And remember - it's easy to iteratively add, remove or update items later as your site evolves. Happy menu building!

Configuring Menu Settings

Identity Settings

When you first create a menu, you'll be asked to set some key identity options - namely the name and handle.

The name can be descriptive, like "Footer Navigation". This is for your reference only in the control panel.

The handle is the unique reference used in templates to output the menu. Go all lowercase, no spaces - "footernav" works great.

You can also add a menu title if you want it to render out with visible text on the front-end. For example, "Footer Site Links" could output before the menu.

These identity settings are important as they allow uniquely identifying and targeting specific menus in your templates. Set them intelligently early on for long-term maintainability.

Other options include adding a custom description and assigning the menu to a site or language, for localization. Take the time to set things up thoughtfully.

Output and Behavior

Beyond just content, the plugin provides several settings that let you control front-end behavior and styling.

Output templates allow defining custom templates for rendering, if you need more granular control over markup and styling vs. the defaults.

You can attach CSS classes to menus and menu items for easy styling hooks - no need to wrestle with complex selectors.

There are also options to restrict navigation by logged-in status, enable automatic subnav collapsing, and more. Configure them to get your desired functionality.

For icons, you can enable the menu items to output SVG icons for extra visual polish. Just assign icons to entries ahead of time.

Really take advantage of these output settings to bend the functionality to your needs, without editing plugin code directly.

Performance Optimization

For complex menus with tons of pages and nesting, performance and caching deserve some attention.

Enabling cache will store a static HTML version of the menu for faster delivery. This prevents slow real-time queries on each request.

But cache invalidation on content changes does become trickier. You'll need to strategize cache settings and tags appropriately.

It's also wise to lazy load any secondary submenus to avoid massive HTML payloads. This defers non-critical markup.

Image optimization should be considered too if icons are enabled. Compress and lazy load those assets.

Basically, apply standard front-end performance best practices to keep your mega menu speedy. Test it out in WebPageTest to catch any issues.

Complex navigations take work to optimize, but it pays dividends in happy users and SEO. Don't neglect those config settings that impact performance!

Displaying Menus in Templates

Basic Twig Examples

Once you've built your Craft navigation menus, displaying them in templates is a breeze with some simple Twig.

Let's say your handle is "mainnav" - outputting the menu is as easy as:

{% set menu = craft.menus.handle('mainnav') %}


{% nav menu %}

{% for item in menu.getItems() %}


<a href="{{ item.url }}">{{ item.title }}</a>


{% endfor %}


That prints out the menu title, iterates through the links, and outputs the anchor tags. Piece of cake!

You can also skip the for loop and use the |raw filter to output menu HTML directly:

{{ menu.getMenuHtml()|raw }}

This prints pre-rendered HTML, no looping required.

Looping Through Items

When you need more control over markup or styling, looping through items is preferred:

{% for child in menu.getItems() %}

{% ifchild.hasChildren() %}

<li class="has-children">

{% else %}


{% endif %}

<a href="{{ child.url }}">{{ child.label }}</a>

{% if child.hasChildren() %}

{% include '_subnav' %}

{% endif %}


{% endfor %}

Now you can add classes, handle edge cases, and partials for submenus.

You can access tons of item properties for advanced logic too - URL, label, target, classes, descendants, and much more.

Troubleshooting Issues

If your menu isn't outputting at all, first check the menu handle is correct. Any typos there will break the output call.

Also confirm the menu is actually enabled in your site's navigation settings. Disabled menus won't render.

For repeated or incorrect items, clear your Craft caches in case of stale data. Menus heavily rely on caches for performance.

If menus show locally but not on production, double check your environment configs sync properly from dev to live.

For wonky styling, inspect the HTML closely and reference the base CSS. You may need to override some properties.

And don't forget JavaScript! Custom JS is often needed for dropdowns, toggles, and hover effects.

Dealing with navigation quirks takes some debugging patience. Enable Twig debugging mode while developing to catch issues early.

But when all else fails, hit up the friendly support forums. The community is full of navigation gurus happy to help!

Customizing Menu Output

Twig Customization

The Navigation plugin makes it easy to customize output right in your Twig templates.

You can pass additional params to tweak things like HTML classes, templates, and more:

{% set params = {

addUlClasses: 'extra-menu-class',

template: 'customTemplate'

} %}

{% nav menu with params %}
For more advanced logic, you can override the default menu templates provided by the plugin. Just copy them to templates/_custom in your Craft site.

You can also create a custom Twig macro to handle all menu output:

{% macro menu(menuHandle) %}

{# Your custom menu output logic #}

{% endmacro %}

{# Output #}

{{ _self.menu(menuHandle) }}

This keeps things reusable while still allowing markup overrides.


To customize styling, use the menu and item class names generously added by the plugin DOM elements.

No need to get overly specific with CSS selectors. Simply target the classes for easy styling hooks.

JS is great for adding interactive flourishes like dropdown toggles, hover effects, active states, and more.

Of course, adapt all front-end code for responsiveness! Mobile-friendly mega menus require careful CSS and JS.

Familiarize yourself with the default markup, classes, and behaviors so you know what needs overriding.

Nested and Mega Menus

For complex nested and mega menus, start by carefully planning the information architecture. Map out all the levels and connections.

Use the control panel to build this hierarchical structure - top level pages first, then drill down for deeper nesting.

Keep mega menu content succinct and scannable. Avoid overload by pruning less critical content.

For styling, use shadows, borders and background colors to visually distinguish menu levels. White space is important too.

Careful CSS is essential so nested submenus display and collapse elegantly. Media queries will help here.

And don't forget - accessibility! Use ARIA attributes appropriately to support assistive devices.

Lastly, rigorously test the finished menu! Poke around on all screen sizes to catch quirks. Don't let a wonky mega menu ship!

With smart planning and some CSS/JS finesse, you can build multi-level menus that both users and search engines will love browsing.

Advanced Plugin Functionality

Complementary Plugins

The Navigation plugin provides robust core features to handle menus in Craft CMS. But for even more advanced capabilities, complementary plugins can extend things further.

For example, Menu Manager by Vartheme adds drag and drop management directly in the control panel for easier reordering.

Retcon's Menu Plus plugin allows multiple menus per site, menu splitting, custom tables, and additional template customization options.

There are also geography and language aware navigation plugins like Switcher by Studioespresso for localizing mega menus.

And the Craft CMS SEO plugin; SEOmatic integrates with Navigation to include menus in site maps and handle automated descriptive alt text.

Explore plugins tagged as "Navigation" on the official store to discover options that build on the core functionality. Integrate them for the perfect menu toolkit!

Custom Templates

While the Navigation plugin comes with robust default markup and styling out of the box, you may eventually want to create completely custom templates on a per menu basis.

For example, you can have a customized mobile-only menu, a specialized footer menu, and so on.

Just copy the default menu.twig template from the plugin source into templates/_custom in your Craft site.

Then rename it something like footer-menu.twig and customize the markup and logic to your needs. Pass your custom template when outputting the menu.

This allows total freedom to tweak templates for individual menus, while keeping the defaults untouched.


Don't forget the JavaScript! While CSS handles presentation, JS powers the interactive behavior that brings menus to life.

For example, the menu toggle on mobile that expands and collapses. Click events to show dropdowns. Hover effects and active states

This usually requires some custom JS tailored to your menu markup and functionality.

Work mobile-first, making sure the scaled down menu works smoothly. Then enhance interactions on wider screens.

Consider accessibility too - customize focus behavior for keyboard and screen reader users.

And optimize performance! Defer non-essential JS, use efficient selectors, and avoid listeners on unused elements.

JS really takes menus from static to dynamic. But be sure to progressively enhance with care - start with the core functionality before getting too fancy.

Shape April 2022 HR 202
Andy Golpys
- Author

Andy has scaled multiple businesses and is a big believer in Craft CMS as a tool that benefits both Designer, Developer and Client. 

Show us some love
Email Us
We usually reply within 72 hours
Agency Directory
Submit your agency
Affiliate Partners
Let's chat