---
title: "useFuzzySearch"
description: "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."
package: "maz-ui"
url: "https://maz-ui.com/composables/use-fuzzy-search"
---

# 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.

- Package: `maz-ui`
- Import: `import { useFuzzySearch } from 'maz-ui/composables/useFuzzySearch'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/composables/use-fuzzy-search

The list is indexed when it changes, and searched when the query changes. The matching is the one of the [fuzzySearch](https://maz-ui.com/ecosystem/utils/fuzzy-search.md) helper of `@maz-ui/utils`.

## Usage

```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](https://maz-ui.com/ecosystem/utils/fuzzy-search.md#options) (`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 |
