useDocsFilterConfig
The sidebar filter is built from three exports of useDocsFilterConfig.ts: useDocsFilterConfig reads the config, useDocsFilterVisible decides whether the input is shown, and filterNavigation filters the groups. The search term is shared by the docs layout through provide('docsFilterSearch', ref('')) and cleared on route change.
Usage
Enable the filter:
export default defineAppConfig({
aside: {
filter: {
enabled: true,
threshold: 10,
shortcut: '/'
}
}
})
Read the config in a custom DocsAsideLeftTop:
<script setup lang="ts">
const searchTerm = inject<Ref<string>>('docsFilterSearch', ref(''), false)
const { placeholder } = useDocsFilterConfig()
</script>
<template>
<UInput v-model="searchTerm" :placeholder="placeholder" />
</template>
Signature
function useDocsFilterConfig(): {
enabled: ComputedRef<boolean>
placeholder: ComputedRef<string>
threshold: ComputedRef<number>
shortcut: ComputedRef<string>
}
function useDocsFilterVisible(): ComputedRef<boolean>
function filterNavigation(
groups: ContentNavigationItem[],
term: string,
scoreItem: (item: ContentNavigationItem, term: string, fields: string[]) => unknown
): ContentNavigationItem[]
Return Value
useDocsFilterConfig():
| Name | Type | Description |
|---|---|---|
enabled | ComputedRef<boolean> | aside.filter.enabled, default false |
placeholder | ComputedRef<string> | aside.filter.placeholder; falls back to the built-in translation docs.filterPlaceholder |
threshold | ComputedRef<number> | aside.filter.threshold, default 10 |
shortcut | ComputedRef<string> | aside.filter.shortcut, default /; an empty string binds no shortcut |
useDocsFilterVisible() returns a ComputedRef<boolean> that is true when the filter is enabled and the groups of the current section contain at least threshold pages in total.
filterNavigation() returns the filtered groups: with an empty term the groups are returned unchanged; otherwise pages are matched on title and description, parents of matching children are kept, and groups without matches are removed. scoreItem usually comes from Nuxt UI's useFilter():
import { useFilter } from '@nuxt/ui/composables'
const { scoreItem } = useFilter()
const filtered = computed(() => filterNavigation(navigationByCategory.value, searchTerm.value, scoreItem))
Related
Changelog
useDocsRoute
Check whether the current route is a docs page, covering /docs/* for the default locale and /{locale}/docs/* for others. Use it in site-wide components such as a custom header or footer that should show something only on docs pages.
useDocsShell
The site shell shared by app.vue and error.vue. It loads the navigation tree and search index for the current locale, sets the html language, direction, font and grain attributes, and provides navigation to the component tree. Call it directly only when you rewrite app.vue or error.vue.