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

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

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

Parameters

NameTypeDescription
navigationRef<ContentNavigationItem[] | undefined>The docs navigation tree, usually from useDocsNavigation()

Return Value

NameTypeDescription
rootNavigationComputedRef<ContentNavigationItem[]>Top-level sections under the docs root, used by the header section bar
navigationByCategoryComputedRef<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.
app/app.config.ts
export default defineAppConfig({
  docs: {
    categories: {
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
      ]
    }
  }
})
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.

Changelog

No recent changes
Copyright © 2024 - 2026