Open menu dropdown
useFuzzySearch
Reactive fuzzy search in a list - prefixes, words in any order, initials, typos and accents, the best matches first, with the matched characters to highlight them.
The list is indexed when it changes, and searched when the query changes. The matching is the one of the fuzzySearch helper of @maz-ui/utils.
Usage
Search a country
- France (FR, score 1.00)
- French Guiana (GF, score 1.00)
- Germany (DE, score 1.00)
- Greece (GR, score 1.00)
- Côte d’Ivoire (CI, score 1.00)
- New Zealand (NZ, score 1.00)
- Papua New Guinea (PG, score 1.00)
- Guinea (GN, score 1.00)
vue
<script lang="ts" setup>
import type { FuzzySearchResult } from '@maz-ui/utils/helpers/fuzzySearch'
import { highlightMatches } from '@maz-ui/utils/helpers/fuzzySearch'
import { useFuzzySearch } from 'maz-ui/composables/useFuzzySearch'
import { ref } from 'vue'
const countries = [
{ code: 'FR', name: 'France' },
{ code: 'DE', name: 'Germany' },
{ code: 'NZ', name: 'New Zealand' },
{ code: 'GB', name: 'United Kingdom' },
{ code: 'US', name: 'United States' },
// ...
]
const query = ref('')
const { results } = useFuzzySearch(countries, query, {
keys: ['name', { key: 'code', weight: 0.8 }],
limit: 8,
})
function getSegments(result: FuzzySearchResult<typeof countries[number]>) {
const match = result.matches.find(item => item.key === 'name')
return highlightMatches(result.item.name, match?.indexes ?? [])
}
</script>
<template>
<MazInput v-model="query" label="Search a country" />
<ul>
<li v-for="result in results" :key="result.item.code">
<template v-for="(segment, index) in getSegments(result)" :key="index">
<mark v-if="segment.match" class="bg-transparent font-semibold text-primary">{{ segment.text }}</mark>
<template v-else>{{ segment.text }}</template>
</template>
</li>
</ul>
</template>Try nwz, kingdom united, germny or cote.
Debounce
With a big list, debounce waits for the end of the typing: isPending is true meanwhile, the previous results stay displayed.
ts
const { items, isPending } = useFuzzySearch(products, query, {
keys: ['title', { key: 'description', weight: 0.5 }],
debounce: 200,
})Reactive options
The list, the query and the options accept refs and getters.
ts
const typoThreshold = ref(0.75)
const { items } = useFuzzySearch(() => store.users, query, () => ({
keys: ['name', 'email'],
typoThreshold: typoThreshold.value,
}))API
ts
function useFuzzySearch<T>(
list: MaybeRefOrGetter<readonly T[] | null | undefined>,
query: MaybeRefOrGetter<string | null | undefined>,
options?: MaybeRefOrGetter<UseFuzzySearchOptions<T>>,
): {
/** The results: item, index, score, matched keys and characters */
results: ComputedRef<FuzzySearchResult<T>[]>
/** The matching items */
items: ComputedRef<T[]>
/** `true` while the debounce runs */
isPending: Ref<boolean>
}An empty query returns every item, in the order of the list.
Options
The options of fuzzySearch (keys, typoThreshold, minScore, sort, limit), and:
| Option | Type | Default | Description |
|---|---|---|---|
debounce | number | 0 | Delay in ms between the last change of the query and the search |