useNavigation
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
<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
| Name | Type | Description |
|---|---|---|
navigation | Ref<ContentNavigationItem[] | undefined> | The docs navigation tree, usually from useDocsNavigation() |
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:
- Pages with no
categoryand no subdirectory go into an "Overview" group (label from the built-in translationdocs.overview). - Each subdirectory becomes its own group, such as "Composables" in the reference section.
- Pages with a
categoryare grouped in the order declared bydocs.categories[section slug]inapp.config; undeclared categories are not shown.
export default defineAppConfig({
docs: {
categories: {
guide: [
{ id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
]
}
}
})
---
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
Changelog
useDocsNavigation
Read the docs navigation tree that the shell has already loaded. The header section bar, sidebar and docs pages all take their navigation from here, so custom components reuse the same data without querying the collection again.
useHeader
Provides the desktop and mobile header navigation links. Declare them in header.nav and header.mobileNav in app.config; override the composable with a same-named file in your project only when links must be generated from runtime state.