{"id":10926,"library":"fzf","title":"FZF Fuzzy Matching Algorithm for JavaScript","description":"FZF for JavaScript is a library that ports the core fuzzy-finding algorithm from the popular FZF CLI tool into a JavaScript-native implementation, making it suitable for both browser and Node.js environments. The current stable version is `v0.5.2`. The project exhibits an active development cadence, with frequent minor releases that, while in `0.x` territory, introduce significant features and occasionally breaking changes. It differentiates itself by offering two distinct fuzzy algorithms (`v1` for speed, `v2` for better highlighting), support for extended search syntax, and an asynchronous finder for maintaining a responsive user interface during complex queries. This library is specifically designed to power command palettes and similar interactive search UIs in modern web applications, providing a robust and performant fuzzy matching experience.","status":"active","version":"0.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/ajitid/fzf-for-js","tags":["javascript","fzf","fuzzy-search","fuzzy-match","fuzzy","search","find","typescript"],"install":[{"cmd":"npm install fzf","lang":"bash","label":"npm"},{"cmd":"yarn add fzf","lang":"bash","label":"yarn"},{"cmd":"pnpm add fzf","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is primarily designed for ESM; CommonJS `require` might lead to issues or incorrect typings, especially in newer Node.js environments or with specific bundler configurations. Prioritize ESM `import`.","wrong":"const { Fzf } = require('fzf')","symbol":"Fzf","correct":"import { Fzf } from 'fzf'"},{"note":"Import types separately using `import type` for clarity and to ensure they are correctly resolved by TypeScript, especially with `moduleResolution` set to `nodenext` or `node16`.","symbol":"FzfOptions","correct":"import type { FzfOptions } from 'fzf'"},{"note":"Access types for the individual matched results returned by `fzf.find()`, which include the `item`, `score`, and `positions`.","symbol":"FzfResultItem","correct":"import type { FzfResultItem } from 'fzf'"}],"quickstart":{"code":"import { Fzf } from 'fzf';\n\nconst programmingLanguages = [\n  'go', 'javascript', 'python', 'rust', \n  'swift', 'kotlin', 'elixir', 'java', \n  'lisp', 'v', 'zig', 'nim', 'rescript', \n  'd', 'haskell'\n];\n\n// Create a new Fzf instance with your list of items\nconst fzf = new Fzf(programmingLanguages, {\n  tiebreakers: ['end', 'length'], // Example option, uses 'end' and 'length' as secondary sort keys\n  limit: 5 // Limit the number of results\n});\n\n// Perform a fuzzy search\nconst query = 'jav';\nconst entries = fzf.find(query);\n\nconsole.log(`Fuzzy search results for '${query}':`);\nentries.forEach(entry => {\n  console.log(`- ${entry.item} (Score: ${entry.score})`);\n});\n// Expected output: javascript, java (order depends on scores and tiebreakers)\n","lang":"typescript","description":"This quickstart initializes `Fzf` with a list of strings and performs a basic fuzzy search, demonstrating how to retrieve and iterate over the sorted results."},"warnings":[{"fix":"Review the new `tiebreakers` behavior in the official documentation and update your `FzfOptions` accordingly to achieve the desired sorting.","message":"The behavior of `options.tiebreakers` was modified in v0.5.1 to align with the original FZF implementation. If you relied on the previous tiebreaker logic, you may need to adjust your options or expected sorting behavior.","severity":"breaking","affected_versions":">=0.5.1"},{"fix":"Always use `v0.5.1` or above. If you accidentally installed `0.5.0`, downgrade or upgrade to a stable version immediately (e.g., `npm install fzf@latest`).","message":"Version 0.5.0 was critically bugged and required Node.js 16 and NPM 8, leading to it being removed from NPM. It should never be used.","severity":"breaking","affected_versions":"0.5.0"},{"fix":"Always pin to exact versions or use carets (`^`) with caution. Thoroughly test updates before deploying to production and review migration guides provided by the library.","message":"As a `0.x` version package, `fzf` reserves the right to introduce breaking changes in minor version increments (e.g., `0.3.x` to `0.4.x`). Always consult migration guides and release notes when updating.","severity":"gotcha","affected_versions":">=0.3.1"},{"fix":"Upgrade to `fzf@0.5.2` or later. If upgrading is not possible, ensure your `tsconfig.json` uses a compatible `moduleResolution` setting (e.g., `node`).","message":"Older versions of `fzf` (prior to `v0.5.2`) had issues with TypeScript `moduleResolution` settings like `nodenext`, `node16`, or `bundler`, which could prevent types from being correctly resolved.","severity":"gotcha","affected_versions":"<0.5.2"},{"fix":"If performance is critical, instantiate `Fzf` with `{ algorithm: 'v1' }` in its options to potentially gain speed at the expense of highlighting quality. Benchmark both options for your specific use case.","message":"The default fuzzy algorithm was changed to 'v2' in v0.4.1 for better highlighting, but 'v1' is faster. Performance-sensitive applications might need to explicitly configure the algorithm.","severity":"gotcha","affected_versions":">=0.4.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `fzf` is installed (`npm i fzf`) and upgrade to `fzf@0.5.2` or later. If upgrading is not feasible, adjust `compilerOptions.moduleResolution` in `tsconfig.json` to `node`.","cause":"Incorrect TypeScript `moduleResolution` settings (e.g., `nodenext`, `node16`, `bundler`) in `tsconfig.json` when using `fzf` versions older than `v0.5.2`, or a missing `fzf` installation.","error":"Cannot find module 'fzf' or its corresponding type declarations."},{"fix":"Use ESM `import { Fzf } from 'fzf'` instead of `const { Fzf } = require('fzf')`. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to import `Fzf` using CommonJS `require()` syntax, but the package is primarily designed for ESM or the default export is not correctly handled in CJS environments.","error":"TypeError: Fzf is not a constructor"},{"fix":"This specific version is known to be problematic. Upgrade to `fzf@0.5.1` or the latest stable version. Avoid using `fzf@0.5.0` entirely.","cause":"Attempting to use `fzf@0.5.0` (which was removed from NPM) in an environment that does not meet its specific, higher Node.js and NPM version requirements.","error":"Error: Package \"fzf\" (v0.5.0) requires Node.js \"^16\" and npm \"^8\"."}],"ecosystem":"npm"}