useDocsFilterConfig

Config, visibility check and filter function behind the sidebar navigation filter, mapped to aside.filter in app.config. Use them in a custom sidebar top or sidebar body component to keep the default filtering behavior.

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:

app/app.config.ts
export default defineAppConfig({
  aside: {
    filter: {
      enabled: true,
      threshold: 10,
      shortcut: '/'
    }
  }
})

Read the config in a custom DocsAsideLeftTop:

app/components/DocsAsideLeftTop.vue
<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():

NameTypeDescription
enabledComputedRef<boolean>aside.filter.enabled, default false
placeholderComputedRef<string>aside.filter.placeholder; falls back to the built-in translation docs.filterPlaceholder
thresholdComputedRef<number>aside.filter.threshold, default 10
shortcutComputedRef<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))

Changelog

No recent changes
Copyright © 2024 - 2026