Fuzzy Search & String Matching

Substring search is strict: "proj" matches "Project settings", but "prj" does not. Real users type partial fragments, skip vowels, and remember words out of habit rather than exact spelling. Fuzzy search makes local filtering feel smarter by treating the query as a sequence of characters that can appear across the target string.

Subsequence Matching

A simple fuzzy matcher walks the query through the title from left to right. Every query character must be found in order, but other characters can appear between them.

export function fuzzyMatchIndices(title: string, query: string): number[] | null {
  const normalizedTitle = title.toLowerCase();
  const normalizedQuery = query.trim().toLowerCase();
  const indices: number[] = [];

  if (normalizedQuery.length === 0) return [];

  let titleIndex = 0;
  for (const queryChar of normalizedQuery) {
    const nextIndex = normalizedTitle.indexOf(queryChar, titleIndex);
    if (nextIndex === -1) return null;
    indices.push(nextIndex);
    titleIndex = nextIndex + 1;
  }

  return indices;
}

This algorithm is small enough to audit and fast enough for hundreds or thousands of items in memory. It will match "rct" against "React Components" because the letters appear in order.

Scoring And Ranking

Matching is only half the experience. Ranking decides what appears first. A compact match is usually more relevant than a match spread across the whole string.

type SearchResult = {
  title: string;
  indices: number[];
  score: number;
};

export function searchTitles(titles: string[], query: string): SearchResult[] {
  return titles
    .map((title) => {
      const indices = fuzzyMatchIndices(title, query);
      if (!indices) return null;
      const score = indices.length === 0
        ? Number.POSITIVE_INFINITY
        : indices[indices.length - 1] - indices[0];
      return { title, indices, score };
    })
    .filter((result): result is SearchResult => result !== null)
    .sort((a, b) => a.score - b.score || a.title.length - b.title.length);
}

Highlighting Matches

Return indices rather than only true so the UI can highlight matched characters. In a component, convert the index list to a Set, then render matched characters with a success color and non-matches with muted text.

export function splitHighlighted(title: string, indices: number[]) {
  const matched = new Set(indices);
  return [...title].map((char, index) => ({
    char,
    matched: matched.has(index),
  }));
}

Further Learning

Search these terms to go deeper:

• “subsequence fuzzy matching algorithm” — the core character-walking approach
• “Fuse.js scoring options” — production-ready fuzzy ranking strategies
• “command palette fuzzy search UX” — how search ranking affects navigation
• “highlight matched characters accessibility” — preserving readable labels while styling matches

Fuzzy Search & String Matching

Ever notice how in tools like VS Code you can type rct and it finds “React Components”? That’s fuzzy search — it matches the letters in order even when they’re not next to each other. It feels smart because it forgives typos and partial memory.

Plain search vs. fuzzy search

• Substring search is strict: "proj" matches “Project” but "prj" finds nothing.
• Fuzzy search is forgiving: "prj" matches “Project” because p, r, j all appear in order.

How it works: walk the letters in order

The core idea is simple. Go through the search letters one by one, and check each appears somewhere after the previous one in the target:

function fuzzyMatch(text, query) {
  text = text.toLowerCase()
  query = query.toLowerCase()
  let pos = 0
  for (const char of query) {
    pos = text.indexOf(char, pos)   // find this letter after the last one
    if (pos === -1) return false    // a letter's missing → no match
    pos++
  }
  return true   // found all letters in order → match!
}

That’s the whole trick — every query letter must appear, in order, somewhere in the text.

Ranking the results

Matching is only half of it — you also want the best matches on top. A simple rule: matches where the letters are close together are usually more relevant than ones spread far apart. So you can score by “how spread out was the match” and sort by that (tighter = better).

Highlighting

If your match function returns which letters matched (their positions), the UI can bold or color just those letters — that satisfying highlight you see in command palettes.

In one sentence

Fuzzy search matches your letters in order even with gaps (so rct finds “React”), by walking each query letter through the text — then ranks tighter matches higher and can highlight the matched letters.

Want to go deeper?

Switch to Expert mode above for the full scoring/ranking function, returning match indices, and libraries like Fuse.js.