Fuse.js Fuzzy Search#

A zero-dependency TypeScript library based on the Bitap algorithm. Works in browsers, Node.js, and Deno.

Installation#

bash

npm install fuse.js           # Full version
npm install fuse.js@beta      # Includes FuseWorker

js

import Fuse from 'fuse.js'          // ESM full version
import Fuse from 'fuse.js/basic'    // Basic version (fuzzy search only)

Minimal Example#

js

const fuse = new Fuse(list, {
  keys: ['title', 'author'],
  includeScore: true,         // Returns score 0-1
  threshold: 0.4,             // 0=exact match, 1=any match (0.3-0.4 recommended for search-as-you-type)
})
fuse.search('jon')            // → [{ item, score, refIndex }]

Usage by Scenario#

Fuzzy Search (Basic)#

js

new Fuse(list, {
  keys: ['name'],
  threshold: 0.4,
  ignoreLocation: true,       // MUST enable for long text, otherwise only searches ~first 60 chars
  includeMatches: true,       // For highlighting
  includeScore: true,
  minMatchCharLength: 2,      // Ignores single-character matches
})

Multi-field Weighted Search#

js

keys: [
  { name: 'title', weight: 2 },
  { name: 'description', weight: 1 },
]

Dot notation: 'author.firstName'. Set ignoreFieldNorm to disable the short-field bonus.

Extended Search (Operators)#

js

{ useExtendedSearch: true }

fuse.search('^java =exact')    // space=AND, |=OR
fuse.search("!deprecated | 'active")

Operators: no prefix=fuzzy, = =exact, ' =contains, ! =exclude, ^ =prefix, .$ =suffix. Requires Fuse.use(ExtendedSearch) for the basic version.

Tokenized Search#

js

{
  useTokenSearch: true,
  tokenMatch: 'any'           // 'any'(OR, default) | 'all'(AND filtering)
}

Multi-word queries are split into independent tokens for fuzzy matching + IDF weighting. Word order is irrelevant, and there is no 32-character length limit. Use the tokenize function + Intl.Segmenter for CJK tokenization. Full version only.

Logical Queries#

js

fuse.search({
  $and: [{ title: 'js' }, { $or: [{ author: 'a' }, { author: 'b' }] }]
})

Highlighting#

includeMatches: true → result.matches[].indices → [[start, end], ...]. Note: end is inclusive.

Dynamic Add/Remove & Single Matching#

js

fuse.add(doc)
fuse.remove(doc => doc.id === 'x')
Fuse.match('patern', 'pattern matching')  // → { isMatch, score, indices }

Web Worker (Large Datasets)#

js

import { FuseWorker } from 'fuse.js/worker'
const fuse = new FuseWorker(docs, { keys: ['title'] })
const r = await fuse.search('q')
fuse.terminate()    // Must clean up

With 4 workers + 100K documents: approximately 3.3x speedup. Browser only. Does not support sortFn/ getFn/ useTokenSearch.

Reference Documentation#

Load as needed:

• options — Complete options API
• examples — Practical patterns and scenario quick reference
• react — React components: debouncing, highlighting, virtualization
• performance — Benchmark data and optimization guide
• vs-semantic — Comparison with semantic search and selection guide

Important Notes#

• Default search only looks at the first ~60 characters of a field → Use ignoreLocation: true for long text.
• Bitap has a single-pattern limit of 32 characters → Use useTokenSearch for long queries.
• FuseWorker is browser only. The search() method returns a Promise. Does not support function options.
• Score: 0 = perfect match, 1 = no match.
• The basic version does not include extended search or tokenized search.