fuzzysort

library3.1.0jsnpmunverified

FuzzySort (fuzzysort) is a JavaScript library providing a fast, SublimeText-like fuzzy searching algorithm. It is designed for high performance, capable of searching thousands of items in under 1ms, while maintaining a small footprint (5kb, 0 dependencies). The current stable version is 3.1.0, with updates released as needed for performance improvements or bug fixes rather than a strict schedule. Key differentiators include its speed, minimal size, and an intuitive API for both simple string matching and complex object searching with multiple keys and custom scoring functions. It offers robust result objects that include score, target, original object reference, and index highlights, enabling rich UI feedback. It ships with TypeScript types for enhanced developer experience.

data

npm install fuzzysort

github ↗package ↗

INSTALL

IMPORT

SIG · FUZZYSORT

fuzzysort

datajavascriptv3.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fuzzysort

✓ import fuzzysort from 'fuzzysort'

✗ import { fuzzysort } from 'fuzzysort'

FuzzySort uses a default export for ESM. All methods like `go` and `single` are properties of the default export.

fuzzysort

✓ const fuzzysort = require('fuzzysort')

CommonJS require pattern for Node.js environments. The `fuzzysort` object exposes all library functions.

fuzzysort

✓ <script src="https://cdn.jsdelivr.net/npm/fuzzysort@3.0.2/fuzzysort.min.js"></script>

For browser environments, FuzzySort exposes a global `fuzzysort` object after being loaded via a script tag. Ensure the version matches your needs.

This example demonstrates both basic and advanced fuzzy searching for a list of objects. It shows how to search by a single key, multiple keys, and how to apply a custom score function to boost results based on object properties. It also illustrates how to use the `highlight` method on results.

import fuzzysort from 'fuzzysort'; interface MyItem { id: number; name: string; tags: string[]; } const items: MyItem[] = [ { id: 1, name: 'Apple Macintosh', tags: ['computer', 'vintage'] }, { id: 2, name: 'Banana Republic', tags: ['clothing', 'brand'] }, { id: 3, name: 'Microsoft Surface', tags: ['computer', 'modern'] }, { id: 4, name: 'Cherry Pie', tags: ['food', 'dessert'] }, ]; // Basic search by a single key 'name' const resultsName = fuzzysort.go('mac', items, { key: 'name' }); console.log('Search by name for "mac":', resultsName.map(r => r.obj.name)); // Advanced search by multiple keys, with custom scoring const resultsAdvanced = fuzzysort.go('surf comp', items, { keys: [ 'name', 'tags' ], scoreFn: r => { // Boost score for items tagged 'computer' if (r.obj && r.obj.tags.includes('computer')) { return r.score * 1.5; } return r.score; }, limit: 5 // Limit to top 5 results }); console.log('Advanced search for "surf comp":', resultsAdvanced.map(r => ({ name: r.obj.name, score: r.score, highlightedName: r[0] ? r[0].highlight('<b>', '</b>') : null, highlightedTags: r[1] ? r[1].highlight('<b>', '</b>') : null })));

Debug

Known issues

gotchaFor optimal performance, especially with static target lists, always 'prepare' your targets using `fuzzysort.prepare(string)` if the strings themselves don't change often. This pre-processes the strings, saving computation on repeated searches.

fix

`targets.forEach(t => t.preparedString = fuzzysort.prepare(t.originalString));` then search `fuzzysort.go('query', targets, {key: 'preparedString'});`

affects: >=3.0.0

gotchaSearching extremely long target strings (e.g., >1000 characters) can significantly degrade performance. It's often more efficient to filter out irrelevant long targets or search only relevant sections.

fix

Pre-filter your target list: `targets = targets.filter(t => t.file.length < 1000);` or consider pre-processing to extract relevant, shorter snippets for searching.

affects: >=3.0.0

gotchaWhen using `fuzzysort.go` with `key` or `keys` options, the returned results array contains `result.obj` which is a reference to your original object. If `key` or `keys` are omitted, `result.obj` will be undefined, and `result.target` will be the string that was searched.

fix

Always use `{ key: 'yourKeyName' }` or `{ keys: ['key1', 'key2'] }` when searching an array of objects if you need to access the original object data in the results.

affects: >=3.0.0

gotchaThe `fuzzysort.highlight()` method, when used without arguments, returns an HTML string. If you're in a React/Vue/Angular context, you might want to pass a custom renderer function to avoid XSS risks or to get component-friendly output.

fix

For UI frameworks, use `result.highlight((match, index) => <span key={index} className="highlight">{match}</span>)` instead of `result.highlight('<b>', '</b>')` to generate framework-specific elements.

affects: >=3.0.0

gotchaWhen using `keys` option for multi-key searching, the individual key results (e.g., `keysResult[0]`, `keysResult[1]`) are 'normal results'. The top-level `keysResult` itself only contains `score` and `obj`, not `target` or `indexes` directly.

fix

Access `target` and `indexes` for a specific key match via its index, e.g., `keysResult[0].target` or `keysResult[1].highlight()`.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: fuzzysort.go is not a function

Attempting to call `fuzzysort.go` without correctly importing `fuzzysort` as a default export, or trying to use named imports for methods.

fix

For ESM, use `import fuzzysort from 'fuzzysort';`. For CommonJS, use `const fuzzysort = require('fuzzysort');`. Ensure you are not trying `import { go } from 'fuzzysort';`.

ReferenceError: fuzzysort is not defined

Attempting to use `fuzzysort` in a browser environment without including the `<script>` tag, or before the script has fully loaded, or in a Node.js environment without `require` or `import`.

fix

For browsers, add `<script src="https://cdn.jsdelivr.net/npm/fuzzysort@3.0.2/fuzzysort.min.js"></script>` to your HTML. For Node.js, ensure `npm i fuzzysort` is run and use `import fuzzysort from 'fuzzysort'` or `const fuzzysort = require('fuzzysort')`.

TypeError: Cannot read properties of undefined (reading 'someProperty')

When searching an array of objects, the `key` or `keys` option was omitted, or the specified key path does not exist on the objects being searched. As a result, `result.obj` or `result[index].obj` might be undefined.

fix

Ensure you provide the `key` option (e.g., `{ key: 'name' }`) or `keys` option (e.g., `{ keys: ['name', 'description'] }`) when searching objects, and verify the key path exists on your target objects.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/farzher/fuzzysort ↗

packagehttps://www.npmjs.com/package/fuzzysort ↗