Fuzzy Ranking (TanStack)

---
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:
  origin: TanStack
  type: core
  library: '@tanstack/match-sorter-utils'
  library_version: '9.2.6'
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

<!-- skill-snippet:check -->

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

```ts
type Person = { name: string; email: string }
const person: Person = { name: 'Ada Lovelace', email: 'ada@example.test' }
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#table-features` and read
its global-filtering reference. 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 `@tanstack/table-core#table-features` and read its global-filtering and sorting references.