# Fuzzy Ranking

Rank fuzzy matches with rankItem, filter with RankingInfo.passed, compare saved ranking...

- Repository: https://github.com/TanStack/table (28539 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-21
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add TanStack/table --skill fuzzy-ranking -g -a claude-code -y`
Codex: `npx skills add TanStack/table --skill fuzzy-ranking -g -a codex -y`
Cursor: `npx skills add TanStack/table --skill fuzzy-ranking -g -a cursor -y`
Gemini CLI: `npx skills add TanStack/table --skill fuzzy-ranking -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/TanStack/table/blob/HEAD/packages/match-sorter-utils/skills/fuzzy-ranking/SKILL.md