> For the complete documentation index, see [llms.txt](https://docs.realmacsoftware.com/elements-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmacsoftware.com/elements-docs/elements-language/guides/navigation-and-recursive-templates.md).
# Navigation & Recursive Templates
Navigation components have a problem no other component family shares: their content is a tree of unknown depth. A user's project might be five flat pages, or a folder inside a folder inside a folder. Your hook receives that tree as [`rw.pages`](/elements-docs/elements-language/component/hooks.js/available-data/rw.pages.md), and your templates have to turn it into markup without knowing in advance how deep it goes. The core answer is a technique this guide covers in full: a template that `@include`s **itself**, once per child level, until the tree runs out.
{% hint style="success" %}
This guide dissects the **Tree** (`com.realmacsoftware.navTree`) and **Menu** (`com.realmacsoftware.navbar`) components from the open-source [Core Pack](/elements-docs/elements-language/dev-resources/open-source-components.md). Open their source alongside this page.
{% endhint %}
## The Page Tree
`rw.pages` is an array of page objects mirroring the project's page list. Each object carries identity (`title`, `url`, `description`), type flags (`isPage`, `isFolder`, `isLink`), state (`isActive`, `hasActiveChild`, `isDraft`), menu metadata (`displayInMenu`, `openInNewWindow`), depth info (`navLevel`, `pageDepth`), and — crucially — its children: `hasPages` plus a nested `pages` array of the same shape. The full field reference lives in [rw.pages](/elements-docs/elements-language/component/hooks.js/available-data/rw.pages.md); everything below uses only those documented fields.
Because children are the same shape as parents, every real traversal is recursive. Tree does its entire preparation in one recursive pass — filtering, ID generation, depth limits, and active-state rollup in a single function:
```javascript
// com.realmacsoftware.navTree/hooks.source.js
// Efficient recursive traversal: include node only if it should be shown
const buildPages = (pages, parentPath = "", relativeLevel = 0) => {
const result = [];
if (!Array.isArray(pages) || pages.length === 0) return result;
// Check if we've reached the maximum depth limit
const hasReachedMaxDepth =
maxLevelsDepth === "manual" && maxLevels > 0 && relativeLevel >= maxLevels;
for (let i = 0; i < pages.length; i += 1) {
const page = pages[i];
if (!(page.displayInMenu && !page.isDraft)) continue;
const slug = slugify(page.title);
const id = parentPath ? parentPath + "-" + slug : slug;
// Only build children if we haven't reached the maximum depth
const children = hasReachedMaxDepth
? []
: buildPages(page.pages || [], id, relativeLevel + 1);
const hasPages = children.length > 0;
const hasActiveChild =
hasPages &&
children.some((c) => c.isActive || c.hasActiveChild);
const processedPage = {
...page,
id,
pages: children,
hasPages,
hasActiveChild,
isTopLevel: relativeLevel === 0,
isSecondLevel: relativeLevel === 1,
isThirdLevel: relativeLevel >= 2,
showPageIcon: pageIconDisplay && relativeLevel === 0,
};
if (processedPage.isActive || hasActiveChild) {
openPages.push(id);
}
result.push(processedPage);
}
return result;
};
```
Five decisions in this function are worth stealing for any nav component:
* **Filter as you walk.** `page.displayInMenu && !page.isDraft` drops drafts and pages excluded from the menu at every level, so the template never needs to know those pages exist.
* **Rebuild derived fields after filtering.** `hasPages` and `hasActiveChild` are recomputed from the *filtered* children — if a folder's only child was a draft, the folder correctly renders as a leaf.
* **Give every node a stable ID.** Slugified titles joined down the parent path (`docs-getting-started`) give the template something to hand to Alpine for expand/collapse state and `localStorage` persistence.
* **Enforce depth in the hook, not the template.** When the user picks a manual depth limit (the inspector's `maxLevelsDepth`/`maxLevels` properties), children beyond the limit are simply never built — the template needs no depth logic at all.
* **Precompute level booleans.** `isTopLevel`/`isSecondLevel`/`isThirdLevel` become single-condition `@if` tests in the template, which matters because template `@if` accepts exactly one condition.
Around this core, the hook also scopes *which* subtree to walk: a `wantedPages` inspector property selects the whole project (`rw.pages`), the active page's children (found with a recursive `findActivePage`), or a manually chosen folder (found with a recursive `findPageByTitle`). Three small recursive helpers, one shared traversal — that's the whole data layer.
## Recursive Includes
Tree's markup layer is two files. The root template renders the top-level list and hands each page to an include:
```html
@each(page in pages)
@include("item", page: page)
@endeach
```
The include is where the technique lives. `include/item.html` renders one node — and for that node's children, includes **itself**. This is the full file (only the decorative chevron SVG is elided):
```html
@if(page.hasPages)
@endif
```
Walk it top to bottom:
* **Line 1, `@if(page.hasPages)`** — the whole file is one fork: branch nodes (pages with children) take the first half, leaves take the `@else` half. This test is the recursion's brain.
* **The branch header `