{"id":10925,"library":"fuzzysort","title":"FuzzySort","description":"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.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/farzher/fuzzysort","tags":["javascript","fuzzy search","fuzzy","search","filter","node","fast","sublime","typescript"],"install":[{"cmd":"npm install fuzzysort","lang":"bash","label":"npm"},{"cmd":"yarn add fuzzysort","lang":"bash","label":"yarn"},{"cmd":"pnpm add fuzzysort","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"FuzzySort uses a default export for ESM. All methods like `go` and `single` are properties of the default export.","wrong":"import { fuzzysort } from 'fuzzysort'","symbol":"fuzzysort","correct":"import fuzzysort from 'fuzzysort'"},{"note":"CommonJS require pattern for Node.js environments. The `fuzzysort` object exposes all library functions.","symbol":"fuzzysort","correct":"const fuzzysort = require('fuzzysort')"},{"note":"For browser environments, FuzzySort exposes a global `fuzzysort` object after being loaded via a script tag. Ensure the version matches your needs.","symbol":"fuzzysort","correct":"<script src=\"https://cdn.jsdelivr.net/npm/fuzzysort@3.0.2/fuzzysort.min.js\"></script>"}],"quickstart":{"code":"import fuzzysort from 'fuzzysort';\n\ninterface MyItem {\n  id: number;\n  name: string;\n  tags: string[];\n}\n\nconst items: MyItem[] = [\n  { id: 1, name: 'Apple Macintosh', tags: ['computer', 'vintage'] },\n  { id: 2, name: 'Banana Republic', tags: ['clothing', 'brand'] },\n  { id: 3, name: 'Microsoft Surface', tags: ['computer', 'modern'] },\n  { id: 4, name: 'Cherry Pie', tags: ['food', 'dessert'] },\n];\n\n// Basic search by a single key 'name'\nconst resultsName = fuzzysort.go('mac', items, { key: 'name' });\nconsole.log('Search by name for \"mac\":', resultsName.map(r => r.obj.name));\n\n// Advanced search by multiple keys, with custom scoring\nconst resultsAdvanced = fuzzysort.go('surf comp', items, {\n  keys: [\n    'name',\n    'tags'\n  ],\n  scoreFn: r => {\n    // Boost score for items tagged 'computer'\n    if (r.obj && r.obj.tags.includes('computer')) {\n      return r.score * 1.5;\n    }\n    return r.score;\n  },\n  limit: 5 // Limit to top 5 results\n});\n\nconsole.log('Advanced search for \"surf comp\":', resultsAdvanced.map(r => ({\n  name: r.obj.name,\n  score: r.score,\n  highlightedName: r[0] ? r[0].highlight('<b>', '</b>') : null,\n  highlightedTags: r[1] ? r[1].highlight('<b>', '</b>') : null\n})));","lang":"typescript","description":"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."},"warnings":[{"fix":"`targets.forEach(t => t.preparedString = fuzzysort.prepare(t.originalString));` then search `fuzzysort.go('query', targets, {key: 'preparedString'});`","message":"For 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"Searching 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Access `target` and `indexes` for a specific key match via its index, e.g., `keysResult[0].target` or `keysResult[1].highlight()`.","message":"When 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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ESM, use `import fuzzysort from 'fuzzysort';`. For CommonJS, use `const fuzzysort = require('fuzzysort');`. Ensure you are not trying `import { go } from 'fuzzysort';`.","cause":"Attempting to call `fuzzysort.go` without correctly importing `fuzzysort` as a default export, or trying to use named imports for methods.","error":"TypeError: fuzzysort.go is not a function"},{"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')`.","cause":"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`.","error":"ReferenceError: fuzzysort is not defined"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'someProperty')"}],"ecosystem":"npm"}