|
| 1 | +--- |
| 2 | +title: useSearchCollection |
| 3 | +description: The useSearchCollection composable provides full-text search powered by SQLite FTS5, with prefix matching, BM25 ranking, and snippets. |
| 4 | +--- |
| 5 | + |
| 6 | +## Usage |
| 7 | + |
| 8 | +Use the auto-imported `useSearchCollection` composable to search across one or more collections. It builds an FTS5 index from content sections and provides instant ranked search results. |
| 9 | + |
| 10 | +```vue [app.vue] |
| 11 | +<script setup lang="ts"> |
| 12 | +const { status, search } = useSearchCollection('docs') |
| 13 | +
|
| 14 | +const query = ref('') |
| 15 | +const results = ref([]) |
| 16 | +
|
| 17 | +watch(query, async (value) => { |
| 18 | + results.value = value ? await search(value) : [] |
| 19 | +}) |
| 20 | +</script> |
| 21 | +``` |
| 22 | + |
| 23 | +::note |
| 24 | +`useSearchCollection` is client-only. The FTS5 index is built in the browser using SQLite WASM. |
| 25 | +:: |
| 26 | + |
| 27 | +## Type |
| 28 | + |
| 29 | +```ts |
| 30 | +function useSearchCollection<T extends keyof PageCollections>( |
| 31 | + collection: MaybeRefOrGetter<T | T[]>, |
| 32 | + opts?: GenerateSearchSectionsOptions & { immediate?: boolean } |
| 33 | +): { |
| 34 | + status: Ref<'idle' | 'loading' | 'ready' | 'error'> |
| 35 | + search: (query: string, opts?: SearchCollectionOptions) => Promise<SearchResult[]> |
| 36 | + init: () => Promise<DatabaseAdapter> |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +## API |
| 41 | + |
| 42 | +### Parameters |
| 43 | + |
| 44 | +- `collection`: A single collection key, an array of collection keys, or a reactive ref/getter. When the value changes, the FTS index is rebuilt for the new collections. |
| 45 | +- `opts`: (Optional) Index-building options: |
| 46 | + - `immediate`: Whether to start building the index immediately. Default is `true`. Set to `false` to defer until the first `search()` call or explicit `init()`. |
| 47 | + - `ignoredTags`: Tags to ignore when extracting section content (e.g., `['code']`). |
| 48 | + - `minHeading`: Minimum heading level to split sections on (e.g., `'h2'`). Default is `'h1'`. |
| 49 | + - `maxHeading`: Maximum heading level to split sections on (e.g., `'h4'`). Default is `'h6'`. |
| 50 | + |
| 51 | +### Return Values |
| 52 | + |
| 53 | +- `status`: A reactive ref indicating the index state: `'idle'`, `'loading'`, `'ready'`, or `'error'`. |
| 54 | +- `search(query, opts?)`: Execute a search query. Returns a promise with ranked results. |
| 55 | + - `query`: The search string. Supports prefix matching automatically (typing `compo` matches "composable"). |
| 56 | + - `opts`: (Optional) Search options: |
| 57 | + - `limit`: Maximum results. Default is `50`. |
| 58 | + - `fields`: Restrict search to specific columns (`'title'` or `'content'`). |
| 59 | + - `minTermLength`: Skip terms shorter than this value. Default is `1`. |
| 60 | + - `weights`: Control ranking behavior. |
| 61 | + - `title`: Boost factor for title matches. Default is `10`. |
| 62 | + - `content`: Boost factor for content matches. Default is `5`. |
| 63 | + - `heading`: Whether higher-level sections (h1 > h2 > h3) rank higher. Default is `true`. |
| 64 | + - `snippet`: Return highlighted text excerpts. |
| 65 | + - `columns`: Which columns to snippet (`['title']`, `['content']`, or both). Default is `['content']`. |
| 66 | + - `around`: Number of tokens around the match. Default is `30`. |
| 67 | + - `tag`: HTML tag for highlighting. Default is `'mark'`. |
| 68 | +- `init()`: Manually trigger index building. Useful when `immediate: false`. |
| 69 | + |
| 70 | +### Result Type |
| 71 | + |
| 72 | +```ts |
| 73 | +interface SearchResult { |
| 74 | + collection: string |
| 75 | + id: string |
| 76 | + title: string |
| 77 | + titles: string[] |
| 78 | + level: number |
| 79 | + content: string |
| 80 | + rank: number |
| 81 | + snippets?: { title?: string, content?: string } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +## Examples |
| 86 | + |
| 87 | +### Basic Search |
| 88 | + |
| 89 | +```vue [SearchPage.vue] |
| 90 | +<script setup lang="ts"> |
| 91 | +const { status, search } = useSearchCollection('docs') |
| 92 | +
|
| 93 | +const query = ref('') |
| 94 | +const results = ref([]) |
| 95 | +
|
| 96 | +async function onSearch() { |
| 97 | + results.value = query.value |
| 98 | + ? await search(query.value, { limit: 20 }) |
| 99 | + : [] |
| 100 | +} |
| 101 | +</script> |
| 102 | +
|
| 103 | +<template> |
| 104 | + <UInput v-model="query" :disabled="status !== 'ready'" @input="onSearch" /> |
| 105 | + <ul> |
| 106 | + <li v-for="result in results" :key="result.id"> |
| 107 | + <NuxtLink :to="result.id">{{ result.title }}</NuxtLink> |
| 108 | + </li> |
| 109 | + </ul> |
| 110 | +</template> |
| 111 | +``` |
| 112 | + |
| 113 | +### Multi-Collection Search |
| 114 | + |
| 115 | +```vue [GlobalSearch.vue] |
| 116 | +<script setup lang="ts"> |
| 117 | +const { status, search } = useSearchCollection(['docs', 'blog']) |
| 118 | +
|
| 119 | +const results = ref([]) |
| 120 | +const query = ref('') |
| 121 | +
|
| 122 | +watch(query, async (value) => { |
| 123 | + results.value = value |
| 124 | + ? await search(value, { |
| 125 | + limit: 20, |
| 126 | + snippet: { columns: ['content'], around: 40 }, |
| 127 | + }) |
| 128 | + : [] |
| 129 | +}) |
| 130 | +</script> |
| 131 | +``` |
| 132 | + |
| 133 | +### Deferred Initialization |
| 134 | + |
| 135 | +```vue [LazySearch.vue] |
| 136 | +<script setup lang="ts"> |
| 137 | +const { status, search, init } = useSearchCollection('docs', { |
| 138 | + immediate: false, |
| 139 | +}) |
| 140 | +
|
| 141 | +async function onFocus() { |
| 142 | + if (status.value === 'idle') { |
| 143 | + await init() |
| 144 | + } |
| 145 | +} |
| 146 | +</script> |
| 147 | +``` |
| 148 | + |
| 149 | +### Reactive Collections |
| 150 | + |
| 151 | +```vue [VersionedSearch.vue] |
| 152 | +<script setup lang="ts"> |
| 153 | +const version = ref('v4') |
| 154 | +const collection = computed(() => `nuxt-${version.value}`) |
| 155 | +
|
| 156 | +const { status, search } = useSearchCollection(collection) |
| 157 | +</script> |
| 158 | +
|
| 159 | +<template> |
| 160 | + <select v-model="version"> |
| 161 | + <option>v3</option> |
| 162 | + <option>v4</option> |
| 163 | + <option>v5</option> |
| 164 | + </select> |
| 165 | +</template> |
| 166 | +``` |
| 167 | + |
| 168 | +When the collection value changes, the FTS index is dropped and rebuilt for the new collections. |
| 169 | + |
| 170 | +## Compared to queryCollectionSearchSections |
| 171 | + |
| 172 | +| | `useSearchCollection` | `queryCollectionSearchSections` + Fuse.js | |
| 173 | +|---|---|---| |
| 174 | +| **Dependencies** | None (built-in FTS5) | Requires external library | |
| 175 | +| **Index** | SQLite inverted index | In-memory JS scan | |
| 176 | +| **Speed** | O(log n) indexed lookup | O(n) per query | |
| 177 | +| **Snippets** | Built-in | Manual | |
| 178 | +| **Typo tolerance** | Prefix only | Full fuzzy (edit distance) | |
| 179 | +| **Multi-collection** | Native | Manual merging | |
| 180 | + |
| 181 | +Use `useSearchCollection` when you need fast, zero-dependency search. Use `queryCollectionSearchSections` with Fuse.js or MiniSearch when you need typo-tolerant fuzzy matching. |
0 commit comments