The Navigation extension allows you to create dynamic, interactive navigation elements anywhere in your help center quickly and easily without being limited by Zendesk’s native page template and objects.
Category lists
Section lists
Article lists
Additional examples can be seen throughout our themes and in our Pattern Library.
The Navigation extension is bundled into all of our themes by default, so you can start using it straight away. You can find the source code for the extension within the extension-navigation.(min.)js file in the theme’s Assets folder.
Our themes allow you to add pre-built navigation menus on the Category, Section and Article pages using theme settings.
-
In Zendesk Guide, click the Customize design icon (
) in the sidebar. -
Click Customize on the theme you want to edit.
-
Expand the Category page elements, Section page elements or Article page elements sections and select a navigation style from the sidebar navigation setting.
Each setting includes a Custom template option which, when selected, allows you to use one of the many navigation patterns from our library.
Use data-element="navigation" on an element to create a dynamic navigation menu.
<div data-element="navigation" data-template="my-custom-template"></div>
<template id="tmpl-my-custom-template">
...
</template>
If data attributes are used you will need to ensure that the allow unsafe HTML setting is enabled within Zendesk Guide.
The Navigation extension can be initialized using JavaScript:
<div id="navigation-element">...</div>
<template id="tmpl-my-custom-template">
...
</template>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', function() {
var navigationElement = document.getElementById('navigation-element');
if (!navigationElement) return;
new Navigation(navigationElement, {
template: 'my-custom-template',
// Other options go here
});
});
</script>
Custom micro-templates
When using a custom micro-template, each object has an additional property (isActive) which specifies whether it’s active (meaning it, or one of its child or descendant objects, is being viewed).
<ul class="list-unstyled">
<% categories.forEach(function(category) { %>
<li>
<a class="<% if (category.isActive) { %> font-bold<% } %>" href="<%= category.html_url %>">
<%= category.name %>
</a>
</li>
<% }) %>
</ul>
You can also access the IDs of the active category, section or article (if any) using activeCategoryId, activeSectionId and activeArticleId:
<ul class="list-unstyled">
<% sections.forEach(function(section) { %>
<li>
<a class="<% if (section.id === activeSectionId) { %> font-bold<% } %>" href="<%= section.html_url %>">
<%= section.name %>
</a>
</li>
<% }) %>
</ul>
This is useful if you’re creating navigation menus with nested subsections, where two or more sections may have an isActive value of true, as activeSectionId represents the section actually being viewed (if any).
Additional custom data can be supplied to the template using the templateData option described below.
<nav id="navigation"></nav>
<script type="text/javascript">
document.addEventListener('DOMContentLoaded', () => {
new Navigation(document.getElementById('navigation'), {
templateData: {
foo: 'bar'
}
});
});
</script>
Which would allow the value of foo to be accessed in a template using <%= foo %>.
Options
Options can be passed via data attributes or JavaScript.
For data attributes, append the option name to data- and use kebab case instead of camel case.
| Name | Type | Default | Description |
|---|---|---|---|
| collection | object | {} | An object containing an array of objects representing categories, sections, articles, topics and/or posts. If the collection is not provided, the extension will fetch the objects specified in the option below from the Zendesk REST API. |
| objects | array | ['categories','sections','articles'] | The list of object types to fetch from the REST API and make available to the template. |
| properties | array | Object properties | The list of object properties from the REST API response to pass to the template. |
| categoryId | stringnumbernull | null | Only return objects from a specific category. |
| sectionId | stringnumbernull | null | Only return objects from a specific section. |
| topicId | stringnumbernull | null | Only return objects from a specific topic. |
| labels | array | [] | Only return articles with specific labels. |
| filter | object | {} | An object containing references to custom filtering functions for each object type, where the key is the type of object (e.g., 'categories'). The default filtering functions filter out draft articles. |
| sort | object | {} | An object containing references to custom sorting functions for each object type, where the key is the type of object (e.g., 'categories'). |
| sortOrder | string | 'asc' | The sort order to use for each object collection. |
| template | stringnull | null | The name of the template to use. |
| templateData | object | {} | Additional data to expose to the template. |
The collection object containing categories, sections, article, topics and/or posts is sorted and organized such that parent objects have access to their children.
<% categories.forEach(function(category) { %>
<% category.sections.forEach(function(section) { %> // This is a child section
...
<% section.sections.forEach(function(subsection) { %> // This is a subsection
...
<% }) %>
<% }) %>
<% }) %>
Object properties
The following object properties are passed to the template by default:
| Name | Description |
|---|---|
id | The ID of the object. |
title | The title of the object (articles and posts). |
name | The title of the object (categories, sections and topics). |
description | The description of the object categories, section and topics). |
html_url | The URL of the object. |
position | The position of the object (categories, sections, articles and topics). |
promoted | Whether or not the object is promoted (articles only). |
pinned | Whether or not the object is pinned (posts only). |
draft | Whether or not the object is a draft (articles only). |
section_id | The ID of the parent section (articles only). |
parent_section_id | The ID of the parent section (sections only). |
category_id | The ID of the parent or ancestor category (sections only). |
topic_id | The ID of the parent topic (posts only). |
created_at | The date and time that the object was created. |
Events
| Class | Properties |
|---|---|
navigation:render | Fires when the navigation menu has been rendered. |
