fuzzy-ranking

name	fuzzy-ranking
description	Rank fuzzy matches with rankItem, filter with RankingInfo.passed, compare saved ranking metadata with compareItems, and configure rankings, thresholds, accessors, min/max bounds, or diacritics. Load for @tanstack/match-sorter-utils itself or fuzzy Table filterMeta wiring.
metadata	{"type":"core","library":"@tanstack/match-sorter-utils","library_version":"9.1.2"}
sources	["TanStack/table:packages/match-sorter-utils/src/index.ts","TanStack/table:docs/framework/react/guide/fuzzy-filtering.md","TanStack/table:examples/react/filters-fuzzy"]

Setup

import { compareItems, rankItem, rankings } from '@tanstack/match-sorter-utils'

const query = 'tan'
const values = ['table', 'tanner', 'router']
export const ranked = values
  .map((value) => ({
    value,
    info: rankItem(value, query, { threshold: rankings.MATCHES }),
  }))
  .filter((entry) => entry.info.passed)
  .sort((a, b) => compareItems(a.info, b.info))

Core Patterns

Separate ranking, filtering, and sorting

Call rankItem once, filter on info.passed, retain the RankingInfo, then order matching results with compareItems.

Rank object fields through accessors

type Person = { name: string; email: string }
const person: Person = { name: 'Ada Lovelace', email: '[e-mail]' }
const info = rankItem(person, 'lov', {
  accessors: [(item) => item.name, (item) => item.email],
})

Accessor options can set a per-accessor threshold plus minRanking/maxRanking bounds.

Store ranking as Table filter metadata

In a Table filterFn, call addMeta?.({ itemRank }). Register the corresponding meta shape with filterMeta: metaHelper<{ itemRank: RankingInfo }>(). A related sortFn reads row.columnFiltersMeta[columnId]?.itemRank and uses compareItems, falling back to an ordinary comparator for ties or absent metadata. For the primary Table composition, load @tanstack/table-core#global-filtering and register the fuzzy filter under filterFns for globalFilterFn: 'fuzzy'.

Common Mistakes

HIGH Numeric rank used as pass flag

Wrong: if (rankItem(value, query).rank) include(value).

Correct: test rankItem(value, query).passed.

Ranks below the configured threshold can still be nonzero; passed records the threshold decision.

Source: TanStack/table:packages/match-sorter-utils/src/index.ts

HIGH Ranking recomputed during sorting

Wrong: call rankItem for both rows on every comparator invocation.

Correct: retain RankingInfo during filtering and pass the stored values to compareItems.

Sorting is called many times; recomputing also risks using different query/options than the filter decision.

Source: TanStack/table:docs/framework/react/guide/fuzzy-filtering.md

MEDIUM compareItems direction reversed twice

Wrong: negate compareItems(a, b) because a larger rank should appear first.

Correct: use compareItems(a, b) directly for ascending fuzzy relevance.

The function already returns -1 when a.rank is greater than b.rank.

Source: TanStack/table:packages/match-sorter-utils/src/index.ts

API Discovery

Inspect node_modules/@tanstack/match-sorter-utils/dist/index.d.ts for the installed RankItemOptions, accessor attributes, ranking constants, and comparator behavior. For TanStack Table metadata integration, load the global-filtering and sorting skills.