match-sorter

Install match-sorter as a project dependency using npm.

npm install match-sorter

The keys option allows you to specify which properties of an object should be used for ranking. You can provide an array of strings for top-level keys, or use dot-notation for nested properties.

• Nested Keys: Use dot-notation (e.g., 'name.first').
• Arrays in Objects: Use dot-notation with a numeric index (e.g., 'name.0.first') or a * wildcard to match across all elements in an array (e.g., 'aliases.*.name.first').
• Array of Values: If a key points to an array, the best match from within that array is used for ranking.
• Property Callbacks: Instead of strings, pass a callback function item => value to resolve the value dynamically. This is useful for complex structures or libraries like Immutable.js.

You can pass an object instead of a string in the keys array to apply specific constraints to a particular key.

• threshold: Sets the minimum match level required for that specific key.
• minRanking: A key with a minimum rank will only be promoted if there is at least a simple match.
• maxRanking: Restricts a key from being promoted beyond a certain rank.

// Apply a specific threshold to the 'name' key
matchSorter(list, 'ed', {
  keys: [{threshold: matchSorter.rankings.STARTS_WITH, key: 'name'}, 'color'],
})

// Restrict 'alias' key to a maximum ranking
matchSorter(tea, 'A', {
  keys: ['tea', {maxRanking: matchSorter.rankings.STARTS_WITH, key: 'alias'}],
})

The threshold option defines the minimum criteria required for a result to be included in the output. The default value is MATCHES.

Available thresholds (ordered from highest priority to lowest):

• CASE_SENSITIVE_EQUAL
• EQUAL
• STARTS_WITH
• WORD_STARTS_WITH
• CONTAINS
• ACRONYM
• MATCHES (default)
• NO_MATCH (returns all items, just sorted by best match)

The sorter option allows you to override the core sorting logic.

• To disable sorting entirely (returning items in their original order but ranked), return the rankedItems as-is.
• To reverse the order, return a reversed copy of the rankedItems.

When sorting arrays of objects, use the keys option to specify which properties to match against. You can use dot-notation for nested properties or a wildcard * to match elements in an array.

Supported key types:

• string: A direct property name or a dot-separated path (e.g., 'user.name').
• ValueGetterKey: A function (item) => string | string[] to extract values.
• KeyAttributesOptions: An object to specify key plus custom threshold, minRanking, or maxRanking for that specific key.

If your data uses separators other than spaces (like _ in snake_case), use a property callback in the keys option to replace the separator with spaces before matching.

const list = [
  {name: 'Janice_Kurtis'},
  {name: 'Fred_Mertz'},
]
// Replace underscores with spaces to allow word matching
matchSorter(list, 'js', {keys: [item => item.name.replace(/_/g, ' ')]})

Use matchSorter to filter and sort an array based on a search string. The function returns a new array containing only the items that match the criteria, sorted by relevance using a sensible ranking algorithm (e.g., case-insensitive equality, starts with, contains, etc.).

import {matchSorter} from 'match-sorter'
// or const {matchSorter} = require('match-sorter')
// or window.matchSorter.matchSorter
const list = ['hi', 'hey', 'hello', 'sup', 'yo']
matchSorter(list, 'h') // ['hello', 'hey', 'hi']
matchSorter(list, 'y') // ['yo', 'hey']
matchSorter(list, 'z') // []

If you need access to the internal ranking metadata computed during the sort (such as the rank value or the index of the item), use matchSorterWithRankInfo. This returns an array of objects containing the original item and its associated ranking information.

import {matchSorterWithRankInfo} from 'match-sorter'

const list = ['hi', 'hey', 'hello', 'sup', 'yo']
const rankedResults = matchSorterWithRankInfo(list, 'h')
// [
//   {
//     item: 'hello',
//     rankedValue: 'hello',
//     rank: 5,
//     keyIndex: -1,
//     keyThreshold: undefined,
//     index: 2,
//   },
//   // ...
// ]