---
title: "queryCollectionNavigation"
description: "The queryCollectionNavigation composable generates the navigation tree of given collection."
canonical_url: "https://content.nuxt.com/docs/utils/query-collection-navigation"
---
# queryCollectionNavigation

> The queryCollectionNavigation composable generates the navigation tree of given collection.

## Usage

Use the auto-imported `queryCollectionNavigation` to generate a navigation tree for a specific collection. This is particularly useful for creating dynamic navigation menus or sidebars based on your content structure.

The function returns a chainable promise that allows you to add additional query conditions:

```vue [pages/[...slug].vue]
<script setup lang="ts">
const { data } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs')
    .where('published', '=', true)
    .order('date', 'DESC')
})
</script>
```

<tip>

The `queryCollectionNavigation` utility is available in both Vue and Nitro. Checkout [Server Usage](#server-usage) for more details on how to use it on the server side.

</tip>

### Navigation metadata with `.navigation.yml`

You can add metadata to a directory using a `.navigation.yml` file.

```yml [.navigation.yml]
title: Getting Started
navigation:
  icon: i-lucide-square-play
```

Directory-level navigation fields should be defined under `navigation:`. These values are merged into the returned `ContentNavigationItem`, so custom flags can live there as well.

```yml [.navigation.yml]
title: Getting Started
navigation:
  icon: i-lucide-square-play
  section: true
  badge: New
```

With that config, `queryCollectionNavigation()` returns a navigation item for the directory with `icon`, `section`, and `badge` available on the item object.

## Type

```ts
function queryCollectionNavigation<T extends keyof PageCollections>(
  collection: T,
  fields?: Array<keyof PageCollections[T]>
): ChainablePromise<T, ContentNavigationItem[]>

interface ChainablePromise<T extends keyof PageCollections, R> extends Promise<R> {
  where(field: keyof PageCollections[T] | string, operator: SQLOperator, value?: unknown): ChainablePromise<T, R>
  andWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
  orWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
  order(field: keyof PageCollections[T], direction: 'ASC' | 'DESC'): ChainablePromise<T, R>
}
```

## API

### `queryCollectionNavigation(collection: CollectionName, extraField: keyof Collection)`

Generate a navigation tree for the specified collection.

- Parameters:

  - `collection`: The key of the defined collection in `content.config.ts`.
  - `extraFields`: (Optional) An array of additional fields to include in the navigation items. (By default `title` and `path` are included in the navigation items.)
- Returns: A chainable promise that resolves to a navigation tree structure. The promise includes methods for adding query conditions:

  - `where(field, operator, value)`: Add a WHERE condition
  - `andWhere(groupFactory)`: Add a grouped AND condition
  - `orWhere(groupFactory)`: Add a grouped OR condition
  - `order(field, direction)`: Add an ORDER BY clause

The navigation tree is generated based on the directory structure and ordering happens based on files [ordering](https://content.nuxt.com/docs/collections/types#ordering-files)

## Examples

Basic usage without additional query conditions:

```vue [pages/[...slug].vue]
<script setup lang="ts">
const { data } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs')
})
</script>

<template>
  <nav>
    <ul v-if="data">
      <li v-for="item in data" :key="item.path">
        <NuxtLink :to="item.path">{{ item.title }}</NuxtLink>
      </li>
    </ul>
  </nav>
</template>
```

Example with additional query conditions and extra fields:

```vue [pages/[...slug].vue]
<script setup lang="ts">
const { data } = await useAsyncData('navigation', () => {
  return queryCollectionNavigation('docs', ['description', 'badge'])
    .where('draft', '=', false)
    .where('partial', '=', false)
    .order('title', 'ASC')
})
</script>

<template>
  <nav>
    <ul v-if="data">
      <li v-for="item in data" :key="item.path">
        <NuxtLink :to="item.path">
          {{ item.title }}
          <span v-if="item.badge" class="badge">{{ item.badge }}</span>
        </NuxtLink>
        <p v-if="item.description">{{ item.description }}</p>
      </li>
    </ul>
  </nav>
</template>
```

## Server Usage

Nuxt Content provides a similar utility to query collections on the server side. The only difference is that you need to pass `event` as the first argument to the `queryCollectionNavigation` function.

```ts [server/api/navigation.ts]
export default eventHandler(async (event) => {
  const navigation = await queryCollectionNavigation(event, 'docs')
  return navigation
})
```

<note>

Make sure to create `server/tsconfig.json` file with the following content to avoid type error.

```json
{
  "extends": "../.nuxt/tsconfig.server.json"
}
```

</note>

---

## Extra utilities to work with navigation

Content module provides some extra utilities to simplify common use cases like building breadcrumb navigation.

### `findPageHeadline(navigation, path, options?)`

Returns the headline (name of the parent folder) for a given path within a navigation tree. Useful for displaying section titles or contextual navigation headers.

- `navigation`: The navigation tree (array of ContentNavigationItem).
- `path`: The current page path.
- `options` (optional):

  - `indexAsChild`: Treat index pages as children.

**Example:**

```ts
import { findPageHeadline } from '@nuxt/content/utils'

const headline = findPageHeadline(navigation, '/docs/guide/getting-started')
// headline is a string that contains the name of the parent folder
```

### `findPageBreadcrumb(navigation, path, options?)`

Returns the breadcrumb trail (array of navigation items) for a given path within a navigation tree. Useful for building breadcrumb navigation components.

- `navigation`: The navigation tree (array of ContentNavigationItem).
- `path`: The current page path.
- `options` (optional):

  - `current`: Include the current page in the breadcrumb.
  - `indexAsChild`: Treat index pages as children.

**Example:**

```ts
import { findPageBreadcrumb } from '@nuxt/content/utils'

const breadcrumb = findPageBreadcrumb(navigation, '/docs/guide/getting-started')
// breadcrumb is an array of navigation items leading to the current page
```

### `findPageChildren(navigation, path, options?)`

Finds and returns the direct children of a given path in the navigation tree.

- `navigation`: The navigation tree (array of ContentNavigationItem).
- `path`: The parent path to find children for.
- `options` (optional):

  - `indexAsChild`: Treat index pages as children.

**Example:**

```ts
import { findPageChildren } from '@nuxt/content/utils'

const children = findPageChildren(navigation, '/docs/guide')
// children is an array of navigation items under '/docs/guide'
```

### `findPageSiblings(navigation, path, options?)`

Returns the sibling navigation items for a given path (i.e., other items with the same parent).

- `navigation`: The navigation tree (array of ContentNavigationItem).
- `path`: The current page path.
- `options` (optional):

  - `indexAsChild`: Treat index pages as children.

**Example:**

```ts
import { findPageSiblings } from '@nuxt/content/utils'

const siblings = findPageSiblings(navigation, '/docs/guide/getting-started')
// siblings is an array of navigation items that share the same parent as the current page
```


## Sitemap

See the full [sitemap](https://content.nuxt.com/sitemap.md) for all pages.