---
title: "useNavigation"
description: "Shape the docs navigation tree for the sidebar - top-level sections, the current section's pages grouped by docs.categories, and breadcrumbs for any path. Use it in a custom sidebar or table of contents to keep the default grouping rules."
canonical_url: "https://docs.mhaibaraai.cn/en/docs/reference/composables/use-navigation"
---
# useNavigation

> Shape the docs navigation tree for the sidebar - top-level sections, the current section's pages grouped by docs.categories, and breadcrumbs for any path. Use it in a custom sidebar or table of contents to keep the default grouping rules.

`useNavigation()` takes a navigation tree and returns three derived values. The default sidebar `DocsAsideLeftBody` and the docs page breadcrumb are both built on it.

## Usage

```vue [app/components/DocsAsideLeftBody.vue]
<script setup lang="ts">
const navigation = useDocsNavigation()
const { navigationByCategory } = useNavigation(navigation)
</script>

<template>
  <section v-for="group in navigationByCategory" :key="group.title">
    <p>{{ group.title }}</p>
    <UContentNavigation :navigation="group.children" />
  </section>
</template>
```

## Signature

```ts
function useNavigation(navigation: Ref<ContentNavigationItem[] | undefined>): {
  rootNavigation: ComputedRef<ContentNavigationItem[]>
  navigationByCategory: ComputedRef<ContentNavigationItem[]>
  findBreadcrumb: (path: string) => BreadcrumbItem[]
}
```

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `navigation` | `Ref<ContentNavigationItem[] \| undefined>` | The docs navigation tree, usually from [`useDocsNavigation()`](https://docs.mhaibaraai.cn/en/docs/reference/composables/use-docs-navigation) |

## Return Value

| Name | Type | Description |
| --- | --- | --- |
| `rootNavigation` | `ComputedRef<ContentNavigationItem[]>` | Top-level sections under the docs root, used by the header section bar |
| `navigationByCategory` | `ComputedRef<ContentNavigationItem[]>` | Page groups of the section the current route belongs to, see the rules below |
| `findBreadcrumb` | `(path: string) => BreadcrumbItem[]` | Breadcrumb from the section down to the given path; each item is a `{ label, to }` link without icon and can be passed to `UBreadcrumb` (`BreadcrumbItem` comes from `@nuxt/ui`) |

## Grouping Rules

`navigationByCategory` uses the first slug segment of the route as the current section and splits its pages into three kinds, output in this order:

1. Pages with no `category` and no subdirectory go into an "Overview" group (label from the built-in translation `docs.overview`).
2. Each subdirectory becomes its own group, such as "Composables" in the reference section.
3. Pages with a `category` are grouped in the order declared by `docs.categories[section slug]` in `app.config`; undeclared categories are not shown.

```ts [app/app.config.ts]
export default defineAppConfig({
  docs: {
    categories: {
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
      ]
    }
  }
})
```

```md [content/docs/2.guide/1.configuration.md]
---
title: Configuration
category: basics
---
```

During a language switch, if the navigation data still belongs to the previous locale, `navigationByCategory` returns an empty array so the page is never rendered with the wrong locale's tree.

## Related

- [Navigation and Categories](https://docs.mhaibaraai.cn/en/docs/guide/navigation)
- [useCategory](https://docs.mhaibaraai.cn/en/docs/reference/composables/use-category)

## Changelog

See commit history for [layer/app/composables/useNavigation.ts](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/composables/useNavigation.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/composables/useNavigation.ts)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
