# fuzzy-ranking

Ranks fuzzy search matches in @tanstack/match-sorter-utils and wires the ranking into TanStack Table filters and sorting.

Skill by TanStack. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add tanstack/table --skill fuzzy-ranking
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add tanstack/table --skill fuzzy-ranking -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 16. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/tanstack/table/fuzzy-ranking)

## Source

[Open the source](https://github.com/tanstack/table/tree/HEAD/packages/match-sorter-utils/skills/fuzzy-ranking). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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.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.
````

- Previous: [migrate-v8-to-v9](https://syn4pse.dev/terminal/tanstack-migrate-v8-to-v9.md)
- Next: [devtools](https://syn4pse.dev/terminal/tanstack-table-devtools.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
