Fuzzy Ranking
Developmentfuzzy-rankingFuzzy Ranking is an Agent Skill for development published in the TanStack/table repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/TanStack/table/blob/HEAD/packages/match-sorter-utils/skills/fuzzy-ranking/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/fuzzy-ranking, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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: '[email protected]' }
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/src/index.ts for the installed RankItemOptions, accessor attributes, ranking constants, and comparator behavior. For TanStack Table metadata integration, load the global-filtering and sorting skills.