Skip to content
rapid-fuzzyrapid-fuzzy

Getting started

rapid-fuzzy is a fuzzy search and string similarity library for JavaScript and TypeScript. Its core is written in Rust: Node.js loads it as a native addon, and browsers, Deno, Bun and Cloudflare Workers can load it as WebAssembly. The API is the same everywhere.

Install

Section titled “Install”
Terminal window
npm install rapid-fuzzy

Node.js 22 or later is required. Prebuilt native binaries are installed automatically for macOS, Linux (glibc and musl) and Windows, on x64 and arm64. Bundlers pick the WebAssembly build for the browser on their own: see Runtimes below.

Search a list of strings

Section titled “Search a list of strings”
import { search, closest } from 'rapid-fuzzy';


const languages = ['TypeScript', 'JavaScript', 'Python', 'Rust', 'Go'];


search('typscript', languages);
// → [{ item: 'TypeScript', score: 0.86, index: 0, positions: [] }]


closest('rst', languages); // → 'Rust'

Results are sorted by relevance, and scores run from 0 to 1. Queries understand a small syntax: ^prefix, suffix$, 'exact, !exclude, and several space-separated terms that can appear in any order.

Search the same data many times

Section titled “Search the same data many times”

For autocomplete, command palettes and file finders, build a FuzzyIndex once. It keeps the items in Rust and is about 10x faster per query than search() on 1,000 to 10,000 items:

import { FuzzyIndex } from 'rapid-fuzzy';


const index = new FuzzyIndex(languages);
index.search('typscript', { maxResults: 5 });
index.add('Zig');
index.destroy(); // free the Rust-side memory when you are done

Search objects

Section titled “Search objects”
import { searchObjects } from 'rapid-fuzzy';


const users = [
  { name: 'John Smith', email: 'john@example.com' },
  { name: 'Jane Doe', email: 'jane@example.com' },
];


searchObjects('jane', users, {
  keys: [{ name: 'name', weight: 2 }, 'email'],
});
// → [{ item: { name: 'Jane Doe', … }, index: 1, score: 1, keyScores: [1, 1] }]

Compare strings

Section titled “Compare strings”
import { levenshtein, jaroWinkler, tokenSortRatio } from 'rapid-fuzzy';


levenshtein('kitten', 'sitting'); // 3
jaroWinkler('MARTHA', 'MARHTA'); // 0.961
tokenSortRatio('New York Mets', 'Mets New York'); // 1

Seven distance metrics and four token-based ratios are included. Each has *Batch and *Many variants for comparing many strings in one call. See String similarity.

Pick your runtime

Section titled “Pick your runtime”
Node.js and SSRNative addon, the WASI fallback, Next.js and Vite SSR.
Browsers and bundlersVite, webpack, Next.js, esbuild and loading from a CDN.
Cloudflare WorkersThe WebAssembly build through the workerd export condition.
Deno and BunThe native addon by default, or WebAssembly with a flag.

Next steps

Section titled “Next steps”
  • Try it in the Playground, which runs the WebAssembly build in your browser.
  • Read How matching works before you pick a minScore.
  • Coming from another library? There are migration guides for fuse.js, fuzzysort, uFuzzy, fuzzball, leven and others.