fzf

library0.5.2jsnpmunverified

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.

http-networking workflow

npm install fzf

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FZF

fzf

http-networkingjavascriptv0.5.2

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.

Fzf

✓ import { Fzf } from 'fzf'

✗ const { Fzf } = require('fzf')

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

FzfOptions

✓ import type { FzfOptions } from 'fzf'

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

FzfResultItem

✓ import type { FzfResultItem } from 'fzf'

Access types for the individual matched results returned by `fzf.find()`, which include the `item`, `score`, and `positions`.

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.

import { Fzf } from 'fzf'; const programmingLanguages = [ 'go', 'javascript', 'python', 'rust', 'swift', 'kotlin', 'elixir', 'java', 'lisp', 'v', 'zig', 'nim', 'rescript', 'd', 'haskell' ]; // Create a new Fzf instance with your list of items const fzf = new Fzf(programmingLanguages, { tiebreakers: ['end', 'length'], // Example option, uses 'end' and 'length' as secondary sort keys limit: 5 // Limit the number of results }); // Perform a fuzzy search const query = 'jav'; const entries = fzf.find(query); console.log(`Fuzzy search results for '${query}':`); entries.forEach(entry => { console.log(`- ${entry.item} (Score: ${entry.score})`); }); // Expected output: javascript, java (order depends on scores and tiebreakers)

Debug

Known issues

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

fix

Review the new `tiebreakers` behavior in the official documentation and update your `FzfOptions` accordingly to achieve the desired sorting.

affects: >=0.5.1

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

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`).

affects: 0.5.0

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

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.

affects: >=0.3.1

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

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`).

affects: <0.5.2

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

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.

affects: >=0.4.1

Errors

Common errors & fixes

Cannot find module 'fzf' or its corresponding type declarations.

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.

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

TypeError: Fzf is not a constructor

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.

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`).

Error: Package "fzf" (v0.5.0) requires Node.js "^16" and npm "^8".

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.

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.

Upgrade

Version history

0.5.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ajitid/fzf-for-js ↗

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

homepagehttps://fzf.netlify.app ↗