ContentSearch
Usage
The ContentSearch component extends the CommandPalette component with built-in @nuxt/content search support, navigation grouping and color mode commands. It supports both client-side Fuse.js filtering and server-side FTS5 full-text search. You can pass any CommandPalette property such as icon, placeholder, etc.
useContentSearch composable: const { open } = useContentSearch().ContentSearch component in a ClientOnly component so it's not rendered on the server.Navigation
Use the navigation prop with queryCollectionNavigation to group search results by section:
<script setup lang="ts">
const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))
</script>
<template>
<UApp>
<ClientOnly>
<LazyUContentSearch
:navigation="navigation"
/>
</ClientOnly>
</UApp>
</template>
Files
Use the files prop with queryCollectionSearchSections to load all search sections upfront and use client-side Fuse.js filtering:
<script setup lang="ts">
const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))
const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs', {
ignoredTags: ['style']
}), {
server: false
})
</script>
<template>
<UApp>
<ClientOnly>
<LazyUContentSearch
:navigation="navigation"
:files="files"
:fuse="{ resultLimit: 20, fuseOptions: { threshold: 0.2 } }"
/>
</ClientOnly>
</UApp>
</template>
fuse prop to configure useFuse options passed to the underlying CommandPalette such as resultLimit (default 12) and fuseOptions.threshold (default 0.1).Search Soon
Use the search prop with useSearchCollection for server-side FTS5 full-text search with highlighted snippets instead of client-side filtering:
@nuxt/content v3.14+.<script setup lang="ts">
const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))
const { search, status, init } = useSearchCollection('content', {
immediate: false,
ignoredTags: ['style']
})
const { open } = useContentSearch()
// Defer index initialization until the user opens the palette when using `immediate: false`
watch(open, (value) => {
if (value && status.value === 'idle') {
init()
}
})
</script>
<template>
<UApp>
<ClientOnly>
<LazyUContentSearch
:navigation="navigation"
:search="search"
:search-status="status"
/>
</ClientOnly>
</UApp>
</template>
search-status so the component can automatically re-trigger the search once the index becomes ready. Use search-delay (default 100ms) to control how long typing must pause before the search fires. The fuse.resultLimit option caps the total results returned across all groups (search results, links, theme, etc.).search prop, you don't need to pass files. The component calls the async search function on each keystroke instead of Fuse.js. Results are automatically mapped and grouped by navigation with highlighted snippets. Unlike the files approach which loads all search sections upfront and lets you browse navigation items before typing, the search prop only returns results after a query is entered.Shortcut
Use the shortcut prop to change the shortcut used in defineShortcuts to open the ContentSearch component. Defaults to meta_k ( K).
<template>
<UApp>
<ClientOnly>
<LazyUContentSearch
shortcut="meta_k"
/>
</ClientOnly>
</UApp>
</template>
Links
Use the links prop to add a group of quick-access links at the top of the command palette:
<script setup lang="ts">
const links = [{
label: 'Docs',
icon: 'i-lucide-book',
to: '/docs/getting-started'
}, {
label: 'Components',
icon: 'i-lucide-box',
to: '/docs/components'
}, {
label: 'Showcase',
icon: 'i-lucide-presentation',
to: '/showcase'
}]
</script>
<template>
<UApp>
<ClientOnly>
<LazyUContentSearch
:links="links"
/>
</ClientOnly>
</UApp>
</template>
Color Mode
By default, a group of commands will be added to the command palette so you can switch between light and dark mode. This will only take effect if the colorMode is not forced in a specific page which can be achieved through definePageMeta:
<script setup lang="ts">
definePageMeta({
colorMode: 'dark'
})
</script>
You can disable this behavior by setting the color-mode prop to false:
<template>
<UApp>
<ClientOnly>
<LazyUContentSearch
:color-mode="false"
/>
</ClientOnly>
</UApp>
</template>
API
Props
| Prop | Default | Type |
|---|---|---|
size | 'md' | "sm" | "md" | "xs" | "lg" | "xl" |
close | true | boolean | Omit<ButtonProps, LinkPropsKeys> Display a close button in the input (useful when inside a Modal for example).
|
shortcut | 'meta_k' | stringKeyboard shortcut to open the search (used by |
links | T[]Links group displayed as the first group in the command palette. | |
navigation | ContentNavigationItem[] | |
files | ContentSearchFile[] | |
fuse | {
fuseOptions: {
ignoreLocation: true,
includeMatches: true,
useTokenSearch: true,
threshold: 0.1,
keys: ['label', 'description', 'suffix']
},
resultLimit: 12,
matchAllWhenSearchEmpty: true
} | UseFuseOptions<T>Options for useFuse passed to the CommandPalette. |
search | (query: string, opts?: ContentSearchOptions | undefined): Promise<ContentSearchResult[]>Async search function (e.g. from | |
searchStatus | "error" | "loading" | "idle" | "ready"Status of the async search index (e.g. from | |
searchDelay | 100 | numberDelay (in milliseconds) before the search is triggered (debounced).
Keeps the input responsive by only running the search after typing settles.
Set to |
colorMode | true | boolean When |
title | string | |
description | string | |
overlay | true | boolean Render an overlay behind the modal. |
transition | true | boolean Animate the modal when opening or closing. |
content | DialogContentProps & Partial<EmitsToProps<DialogContentImplEmits>>The content of the modal. | |
dismissible | true | boolean When |
fullscreen | false | boolean When |
modal | boolean The modality of the dialog When set to | |
portal | true | string | false | true | HTMLElementRender the modal in a portal. |
icon | appConfig.ui.icons.search | anyThe icon displayed in the input. |
placeholder | t('commandPalette.placeholder') | stringThe placeholder text for the input. |
autofocus | true | boolean Automatically focus the input when component is mounted. |
loading | boolean When | |
loadingIcon | appConfig.ui.icons.loading | anyThe icon when the |
closeIcon | appConfig.ui.icons.close | anyThe icon displayed in the close button. |
groups | CommandPaletteGroup<ContentSearchItem>[] | |
searchTerm | '' | string |
ui | { modal?: ClassNameValue; input?: ClassNameValue; } & { root?: ClassNameValue; input?: ClassNameValue; close?: ClassNameValue; back?: ClassNameValue; content?: ClassNameValue; footer?: ClassNameValue; viewport?: ClassNameValue; group?: ClassNameValue; empty?: ClassNameValue; label?: ClassNameValue; item?: ClassNameValue; itemLeadingIcon?: ClassNameValue; itemLeadingAvatar?: ClassNameValue; itemLeadingAvatarSize?: ClassNameValue; itemLeadingChip?: ClassNameValue; itemLeadingChipSize?: ClassNameValue; itemTrailing?: ClassNameValue; itemTrailingIcon?: ClassNameValue; itemTrailingHighlightedIcon?: ClassNameValue; itemTrailingKbds?: ClassNameValue; itemTrailingKbdsSize?: ClassNameValue; itemWrapper?: ClassNameValue; itemLabel?: ClassNameValue; itemLabelBase?: ClassNameValue; itemLabelPrefix?: ClassNameValue; itemLabelSuffix?: ClassNameValue; itemDescription?: ClassNameValue; } |
Slots
| Slot | Type |
|---|---|
empty | { searchTerm: string; } |
footer | { ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
back | { ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
close | { ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
item | { item: ContentSearchItem; index: number; ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
item-leading | { item: ContentSearchItem; index: number; ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
item-label | { item: ContentSearchItem; index: number; ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
item-description | { item: ContentSearchItem; index: number; ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
item-trailing | { item: ContentSearchItem; index: number; ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
group-label | { group: CommandPaletteGroup<ContentSearchItem>; label: string; ui: { root: (props?: Record<string, any> | undefined) => string; input: (props?: Record<string, any> | undefined) => string; close: (props?: Record<string, any> | undefined) => string; back: (props?: Record<string, any> | undefined) => string; content: (props?: Record<string, any> | undefined) => string; footer: (props?: Record<string, any> | undefined) => string; viewport: (props?: Record<string, any> | undefined) => string; group: (props?: Record<string, any> | undefined) => string; empty: (props?: Record<string, any> | undefined) => string; label: (props?: Record<string, any> | undefined) => string; item: (props?: Record<string, any> | undefined) => string; itemLeadingIcon: (props?: Record<string, any> | undefined) => string; itemLeadingAvatar: (props?: Record<string, any> | undefined) => string; itemLeadingAvatarSize: (props?: Record<string, any> | undefined) => string; itemLeadingChip: (props?: Record<string, any> | undefined) => string; itemLeadingChipSize: (props?: Record<string, any> | undefined) => string; itemTrailing: (props?: Record<string, any> | undefined) => string; itemTrailingIcon: (props?: Record<string, any> | undefined) => string; itemTrailingHighlightedIcon: (props?: Record<string, any> | undefined) => string; itemTrailingKbds: (props?: Record<string, any> | undefined) => string; itemTrailingKbdsSize: (props?: Record<string, any> | undefined) => string; itemWrapper: (props?: Record<string, any> | undefined) => string; itemLabel: (props?: Record<string, any> | undefined) => string; itemLabelBase: (props?: Record<string, any> | undefined) => string; itemLabelPrefix: (props?: Record<string, any> | undefined) => string; itemLabelSuffix: (props?: Record<string, any> | undefined) => string; itemDescription: (props?: Record<string, any> | undefined) => string; }; } |
content | { close: () => void; } |
Emits
| Event | Type |
|---|---|
update:searchTerm | [value: string] |
Expose
When accessing the component via a template ref, you can use the following:
| Name | Type |
|---|---|
commandPaletteRef | Ref<InstanceType<typeof UCommandPalette> | null> |
Theme
export default defineAppConfig({
ui: {
contentSearch: {
slots: {
modal: '',
input: ''
},
variants: {
fullscreen: {
false: {
modal: 'sm:max-w-3xl h-full sm:h-[28rem]'
}
},
size: {
xs: {},
sm: {},
md: {},
lg: {},
xl: {}
}
},
defaultVariants: {
size: 'md'
}
}
}
})
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
ui: {
contentSearch: {
slots: {
modal: '',
input: ''
},
variants: {
fullscreen: {
false: {
modal: 'sm:max-w-3xl h-full sm:h-[28rem]'
}
},
size: {
xs: {},
sm: {},
md: {},
lg: {},
xl: {}
}
},
defaultVariants: {
size: 'md'
}
}
}
})
]
})